ArmTrngLib.c File Reference

#include <Base.h>
#include <Library/ArmLib.h>
#include <Library/ArmMonitorLib.h>
#include <Library/BaseMemoryLib.h>
#include <Library/DebugLib.h>
#include "ArmTrngDefs.h"

Go to the source code of this file.

Functions
STATIC RETURN_STATUS	TrngStatusToReturnStatus (IN INT32 TrngStatus)
RETURN_STATUS EFIAPI	GetArmTrngVersion (OUT UINT16 *MajorRevision, OUT UINT16 *MinorRevision)
STATIC RETURN_STATUS EFIAPI	GetArmTrngFeatures (IN CONST UINT32 FunctionId, OUT UINT32 *Capability OPTIONAL)
RETURN_STATUS EFIAPI	GetArmTrngUuid (OUT GUID *Guid)
UINTN EFIAPI	GetArmTrngMaxSupportedEntropyBits (VOID)
RETURN_STATUS EFIAPI	GetArmTrngEntropy (IN UINTN EntropyBits, IN UINTN BufferSize, OUT UINT8 *Buffer)
RETURN_STATUS EFIAPI	ArmTrngLibConstructor (VOID)

Detailed Description

Arm Firmware TRNG interface library.

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
• FID - Function ID

Definition in file ArmTrngLib.c.

Function Documentation

ArmTrngLibConstructor()

RETURN_STATUS EFIAPI ArmTrngLibConstructor

(

VOID

)

The constructor checks that the FW-TRNG interface is supported by the host firmware.

It will ASSERT() if FW-TRNG is not supported. It will always return RETURN_SUCCESS.

Return values

RETURN_SUCCESS

The constructor always returns RETURN_SUCCESS.

Definition at line 318 of file ArmTrngLib.c.

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.

GetArmTrngFeatures()

STATIC RETURN_STATUS EFIAPI GetArmTrngFeatures	(	IN CONST UINT32	FunctionId,
		OUT UINT32 *Capability	OPTIONAL
	)

Get the features supported by the Arm TRNG backend.

The caller can determine if functions defined in the Arm TRNG ABI are present in the ABI implementation.

Parameters

[in]	FunctionId	Function Id.
[out]	Capability	Function specific capability if present.

Return values

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

Definition at line 126 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.

TrngStatusToReturnStatus()

STATIC RETURN_STATUS TrngStatusToReturnStatus

(

IN INT32

TrngStatus

)

Convert TRNG status codes to RETURN status codes.

Parameters

[in]

TrngStatus

TRNG status code.

Return values

RETURN_SUCCESS	Success.
RETURN_UNSUPPORTED	Function not implemented or negative return code.
RETURN_INVALID_PARAMETER	A parameter is invalid.
RETURN_NOT_READY	No Entropy available.

Definition at line 41 of file ArmTrngLib.c.