+/** @file\r
+ Arm TRNG interface library definitions (Cf. [1]).\r
+\r
+ Copyright (c) 2021 - 2022, Arm Limited. All rights reserved.<BR>\r
+\r
+ SPDX-License-Identifier: BSD-2-Clause-Patent\r
+\r
+ @par Reference(s):\r
+ - [1] Arm True Random Number Generator Firmware, Interface 1.0,\r
+ Platform Design Document.\r
+ (https://developer.arm.com/documentation/den0098/latest/)\r
+ - [2] NIST Special Publication 800-90B, Recommendation for the Entropy\r
+ Sources Used for Random Bit Generation.\r
+ (https://csrc.nist.gov/publications/detail/sp/800-90b/final)\r
+\r
+ @par Glossary:\r
+ - TRNG - True Random Number Generator\r
+**/\r
+\r
+#ifndef ARM_TRNG_LIB_H_\r
+#define ARM_TRNG_LIB_H_\r
+\r
+/** Get the version of the Arm TRNG backend.\r
+\r
+ A TRNG may be implemented by the system firmware, in which case this\r
+ function shall return the version of the Arm TRNG backend.\r
+ The implementation must return NOT_SUPPORTED if a Back end is not present.\r
+\r
+ @param [out] MajorRevision Major revision.\r
+ @param [out] MinorRevision Minor revision.\r
+\r
+ @retval RETURN_SUCCESS The function completed successfully.\r
+ @retval RETURN_INVALID_PARAMETER Invalid parameter.\r
+ @retval RETURN_UNSUPPORTED Backend not present.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+GetArmTrngVersion (\r
+ OUT UINT16 *MajorRevision,\r
+ OUT UINT16 *MinorRevision\r
+ );\r
+\r
+/** Get the UUID of the Arm TRNG backend.\r
+\r
+ A TRNG may be implemented by the system firmware, in which case this\r
+ function shall return the UUID of the TRNG backend.\r
+ Returning the Arm TRNG UUID is optional and if not implemented,\r
+ RETURN_UNSUPPORTED shall be returned.\r
+\r
+ Note: The caller must not rely on the returned UUID as a trustworthy Arm TRNG\r
+ Back end identity\r
+\r
+ @param [out] Guid UUID of the Arm TRNG backend.\r
+\r
+ @retval RETURN_SUCCESS The function completed successfully.\r
+ @retval RETURN_INVALID_PARAMETER Invalid parameter.\r
+ @retval RETURN_UNSUPPORTED Function not implemented.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+GetArmTrngUuid (\r
+ OUT GUID *Guid\r
+ );\r
+\r
+/** Returns maximum number of entropy bits that can be returned in a single\r
+ call.\r
+\r
+ @return Returns the maximum number of Entropy bits that can be returned\r
+ in a single call to GetArmTrngEntropy().\r
+**/\r
+UINTN\r
+EFIAPI\r
+GetArmTrngMaxSupportedEntropyBits (\r
+ VOID\r
+ );\r
+\r
+/** Returns N bits of conditioned entropy.\r
+\r
+ See [2] Section 2.3.1 GetEntropy: An Interface to the Entropy Source\r
+ GetEntropy\r
+ Input:\r
+ bits_of_entropy: the requested amount of entropy\r
+ Output:\r
+ entropy_bitstring: The string that provides the requested entropy.\r
+ status: A Boolean value that is TRUE if the request has been satisfied,\r
+ and is FALSE otherwise.\r
+\r
+ @param [in] EntropyBits Number of entropy bits requested.\r
+ @param [in] BufferSize Size of the Buffer in bytes.\r
+ @param [out] Buffer Buffer to return the entropy bits.\r
+\r
+ @retval RETURN_SUCCESS The function completed successfully.\r
+ @retval RETURN_INVALID_PARAMETER Invalid parameter.\r
+ @retval RETURN_UNSUPPORTED Function not implemented.\r
+ @retval RETURN_BAD_BUFFER_SIZE Buffer size is too small.\r
+ @retval RETURN_NOT_READY No Entropy available.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+GetArmTrngEntropy (\r
+ IN UINTN EntropyBits,\r
+ IN UINTN BufferSize,\r
+ OUT UINT8 *Buffer\r
+ );\r
+\r
+#endif // ARM_TRNG_LIB_H_\r