ArmTrngLib.h File Reference

Go to the source code of this file.

Functions
RETURN_STATUS EFIAPI	GetArmTrngVersion (OUT UINT16 *MajorRevision, OUT UINT16 *MinorRevision)
RETURN_STATUS EFIAPI	GetArmTrngUuid (OUT GUID *Guid)
UINTN EFIAPI	GetArmTrngMaxSupportedEntropyBits (VOID)
RETURN_STATUS EFIAPI	GetArmTrngEntropy (IN UINTN EntropyBits, IN UINTN BufferSize, OUT UINT8 *Buffer)

Detailed Description

Arm TRNG interface library definitions (Cf. [1]).

Copyright (c) 2021 - 2022, Arm Limited. All rights reserved.

SPDX-License-Identifier: BSD-2-Clause-Patent

Reference(s):

• [1] Arm True Random Number Generator Firmware, Interface 1.0, Platform Design Document. (https://developer.arm.com/documentation/den0098/latest/)
• [2] NIST Special Publication 800-90B, Recommendation for the Entropy Sources Used for Random Bit Generation. (https://csrc.nist.gov/publications/detail/sp/800-90b/final)

Glossary:

• TRNG - True Random Number Generator

Definition in file ArmTrngLib.h.

Function Documentation

GetArmTrngEntropy()

RETURN_STATUS EFIAPI GetArmTrngEntropy	(	IN UINTN	EntropyBits,
		IN UINTN	BufferSize,
		OUT UINT8 *	Buffer
	)

Returns N bits of conditioned entropy.

See [2] Section 2.3.1 GetEntropy: An Interface to the Entropy Source GetEntropy Input: bits_of_entropy: the requested amount of entropy Output: entropy_bitstring: The string that provides the requested entropy. status: A Boolean value that is TRUE if the request has been satisfied, and is FALSE otherwise.

Parameters

[in]	EntropyBits	Number of entropy bits requested.
[in]	BufferSize	Size of the Buffer in bytes.
[out]	Buffer	Buffer to return the entropy bits.

Return values

RETURN_SUCCESS	The function completed successfully.
RETURN_INVALID_PARAMETER	Invalid parameter.
RETURN_UNSUPPORTED	Function not implemented.
RETURN_BAD_BUFFER_SIZE	Buffer size is too small.
RETURN_NOT_READY	No Entropy available.

Definition at line 247 of file ArmTrngLib.c.

GetArmTrngMaxSupportedEntropyBits()

UINTN EFIAPI GetArmTrngMaxSupportedEntropyBits

(

VOID

)

Returns maximum number of entropy bits that can be returned in a single call.

Returns

Returns the maximum number of Entropy bits that can be returned in a single call to GetArmTrngEntropy().

Definition at line 217 of file ArmTrngLib.c.

GetArmTrngUuid()

RETURN_STATUS EFIAPI GetArmTrngUuid

(

OUT GUID *

Guid

)

Get the UUID of the Arm TRNG backend.

A TRNG may be implemented by the system firmware, in which case this function shall return the UUID of the TRNG backend. Returning the Arm TRNG UUID is optional and if not implemented, RETURN_UNSUPPORTED shall be returned.

Note: The caller must not rely on the returned UUID as a trustworthy Arm TRNG Back end identity

Parameters

[out]

Guid

UUID of the Arm TRNG backend.

Return values

RETURN_SUCCESS	The function completed successfully.
RETURN_INVALID_PARAMETER	Invalid parameter.
RETURN_UNSUPPORTED	Function not implemented.

Definition at line 170 of file ArmTrngLib.c.

GetArmTrngVersion()

RETURN_STATUS EFIAPI GetArmTrngVersion	(	OUT UINT16 *	MajorRevision,
		OUT UINT16 *	MinorRevision
	)

Get the version of the Arm TRNG backend.

A TRNG may be implemented by the system firmware, in which case this function shall return the version of the Arm TRNG backend. The implementation must return NOT_SUPPORTED if a Back end is not present.

Parameters

[out]	MajorRevision	Major revision.
[out]	MinorRevision	Minor revision.

Return values

RETURN_SUCCESS	The function completed successfully.
RETURN_INVALID_PARAMETER	Invalid parameter.
RETURN_UNSUPPORTED	Backend not present.

Definition at line 82 of file ArmTrngLib.c.