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