From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from EUR04-VI1-obe.outbound.protection.outlook.com (EUR04-VI1-obe.outbound.protection.outlook.com [40.107.8.70]) by mx.groups.io with SMTP id smtpd.web11.14654.1633017207927246736 for ; Thu, 30 Sep 2021 08:53:28 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@armh.onmicrosoft.com header.s=selector2-armh-onmicrosoft-com header.b=N8CG04QA; spf=pass (domain: arm.com, ip: 40.107.8.70, mailfrom: sami.mujawar@arm.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; s=selector2-armh-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=+Il5ie4/RGcpvO3P0ml9BqmYV0A3lZwuWgoJp3J++og=; b=N8CG04QAMo8erz+eK13tPCsnjHAB+hoYWwPjCeUhN5Xu2La5v3frfaGsbpYKifkFEjko+JpNzYK07+iVElp4GFdACQ0ChDh7IY2iRbSEw5bx1TUrv6u2yX+zeEB9T8WRARTiA8TPCviGBIBc6rEEP/VXugh/3vUyqNsMLA5qklA= Received: from AS9PR06CA0289.eurprd06.prod.outlook.com (2603:10a6:20b:45a::29) by DB6PR0801MB1719.eurprd08.prod.outlook.com (2603:10a6:4:3a::18) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4544.16; Thu, 30 Sep 2021 15:53:12 +0000 Received: from VE1EUR03FT064.eop-EUR03.prod.protection.outlook.com (2603:10a6:20b:45a:cafe::6d) by AS9PR06CA0289.outlook.office365.com (2603:10a6:20b:45a::29) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4566.14 via Frontend Transport; Thu, 30 Sep 2021 15:53:12 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 63.33.187.114) smtp.mailfrom=arm.com; edk2.groups.io; dkim=pass (signature was verified) header.d=armh.onmicrosoft.com;edk2.groups.io; dmarc=pass action=none header.from=arm.com; Received-SPF: Pass (protection.outlook.com: domain of arm.com designates 63.33.187.114 as permitted sender) receiver=protection.outlook.com; client-ip=63.33.187.114; helo=64aa7808-outbound-2.mta.getcheckrecipient.com; Received: from 64aa7808-outbound-2.mta.getcheckrecipient.com (63.33.187.114) by VE1EUR03FT064.mail.protection.outlook.com (10.152.19.210) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4566.14 via Frontend Transport; Thu, 30 Sep 2021 15:53:12 +0000 Received: ("Tessian outbound 0e48c0de19a3:v103"); Thu, 30 Sep 2021 15:53:12 +0000 X-CheckRecipientChecked: true X-CR-MTA-CID: d07357faefae0e18 X-CR-MTA-TID: 64aa7808 Received: from 3645dc4442f6.1 by 64aa7808-outbound-1.mta.getcheckrecipient.com id FA7B68F0-1167-4F3B-AC0A-DE6CD8D0E37F.1; Thu, 30 Sep 2021 15:40:46 +0000 Received: from EUR03-AM5-obe.outbound.protection.outlook.com by 64aa7808-outbound-1.mta.getcheckrecipient.com with ESMTPS id 3645dc4442f6.1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384); Thu, 30 Sep 2021 15:40:46 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=I1nNnz3qnLamM9499a9o+u5BGGWn7VOqBFIOevvgp3g80pfgBIZscgFkFGJkzd2CjQSAHHKHFqpPf4IRwIMRSI3YwYwvp+58D01ad4ND/0Yt/E0hh8+/oJ622zVQjFJ1Zc9GRw2J13rdpJJ6z4meS3eKWznlKf8IT/Rq/VUP/R0bL0dVJj1aQbiOcp3JVqacWVECDXYnDjiSOc+4q1mZgBqlu5zaevDO4HdNFEP54f9pwY8YJSTQEQ6i+26xhQjmJFlkQkSVawcK8ZcFQHL4mEsq0j+Lrksu4/FEDEwhUtNGRanu8aZbbhL2iuFb2c2bULhDL4gXNdBE8Xar7E+6mA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version; bh=+Il5ie4/RGcpvO3P0ml9BqmYV0A3lZwuWgoJp3J++og=; b=LR1NFVG8vX0N8Ch6AQva6d7g6dc/89fhO5vER7fZ+FnZiFBJ4qbf6vfG29km9wtpgm9h54oisudcSi7n50yXVjlALxXwUoQDYB0E63C5CEEfOgzrXlPRt71buwCPofk/hgpthWnCojNdUigvD7NocAeIU/0bMXodN8fT1MN5cknG/BOM1f/qCLR9vWtGs0S4dll0mEqWHszJdjzo7ah1EMmJ5nqorjFlih9ww2rqyGP01MGg2HzRFeS6Tjx/o8o5Dpo01FSOuB5p58/HbZqbd5CBWAtt/FIj3cfWBUxCN6b7Aur95LlVMq7rW4QKWbo45tNGHJ7X2Dqlgtz9E42dIg== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass (sender ip is 40.67.248.234) smtp.rcpttodomain=edk2.groups.io smtp.mailfrom=arm.com; dmarc=pass (p=none sp=none pct=100) action=none header.from=arm.com; dkim=none (message not signed); arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; s=selector2-armh-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=+Il5ie4/RGcpvO3P0ml9BqmYV0A3lZwuWgoJp3J++og=; b=N8CG04QAMo8erz+eK13tPCsnjHAB+hoYWwPjCeUhN5Xu2La5v3frfaGsbpYKifkFEjko+JpNzYK07+iVElp4GFdACQ0ChDh7IY2iRbSEw5bx1TUrv6u2yX+zeEB9T8WRARTiA8TPCviGBIBc6rEEP/VXugh/3vUyqNsMLA5qklA= Received: from AM6P194CA0007.EURP194.PROD.OUTLOOK.COM (2603:10a6:209:90::20) by AM6PR08MB4166.eurprd08.prod.outlook.com (2603:10a6:20b:a6::16) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4544.13; Thu, 30 Sep 2021 15:40:44 +0000 Received: from VE1EUR03FT004.eop-EUR03.prod.protection.outlook.com (2603:10a6:209:90:cafe::9e) by AM6P194CA0007.outlook.office365.com (2603:10a6:209:90::20) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4566.14 via Frontend Transport; Thu, 30 Sep 2021 15:40:44 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 40.67.248.234) smtp.mailfrom=arm.com; edk2.groups.io; dkim=none (message not signed) header.d=none;edk2.groups.io; dmarc=pass action=none header.from=arm.com; Received-SPF: Pass (protection.outlook.com: domain of arm.com designates 40.67.248.234 as permitted sender) receiver=protection.outlook.com; client-ip=40.67.248.234; helo=nebula.arm.com; Received: from nebula.arm.com (40.67.248.234) by VE1EUR03FT004.mail.protection.outlook.com (10.152.18.106) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.4566.14 via Frontend Transport; Thu, 30 Sep 2021 15:40:43 +0000 Received: from AZ-NEU-EX03.Arm.com (10.251.24.31) by AZ-NEU-EX03.Arm.com (10.251.24.31) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2308.14; Thu, 30 Sep 2021 15:40:46 +0000 Received: from E114225.Arm.com (10.1.196.43) by mail.arm.com (10.251.24.31) with Microsoft SMTP Server id 15.1.2308.14 via Frontend Transport; Thu, 30 Sep 2021 15:40:46 +0000 From: "Sami Mujawar" To: CC: Sami Mujawar , , , , , , , , , , , , , Subject: [PATCH v1 1/9] MdePkg: Definition for TRNG library class interface Date: Thu, 30 Sep 2021 16:40:36 +0100 Message-ID: <20210930154044.37336-2-sami.mujawar@arm.com> X-Mailer: git-send-email 2.16.2.windows.1 In-Reply-To: <20210930154044.37336-1-sami.mujawar@arm.com> References: <20210930154044.37336-1-sami.mujawar@arm.com> MIME-Version: 1.0 X-EOPAttributedMessage: 1 X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: 75f19c24-82d2-4694-664c-08d9842a6883 X-MS-TrafficTypeDiagnostic: AM6PR08MB4166:|DB6PR0801MB1719: X-Microsoft-Antispam-PRVS: x-checkrecipientrouted: true NoDisclaimer: true X-MS-Oob-TLC-OOBClassifiers: OLM:5516;OLM:5516; X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam-Untrusted: BCL:0; X-Microsoft-Antispam-Message-Info-Original: k++RhndvZcipMPAiYtmcMfF8g1fYvwC661/Qy+kxzV5NYYt3TX/aEkBSBDmsKw2t92JoQLIxTcKe1OZkObBvpovZzVuqiG6Nl/SImcYK/p3nlQqY+QWfwNeC8Yi40KzCb8k8mtrF+X8Up6LT1lcvw2gYmDAsZy3DUwBppxUG4sIARnX0ht96nrQlvIS/IdtxZ5ODREhrkY7fkClU7AHdMHU8F2P5SYwyaVLvW3S6AINN/62vQ0aFCg3C52HqZKMI1wlfhKJgvxfi9ork3aHTHxT/GlG/AoR/p5ejOmTOs//CpfVXeFg6umrUXYZueK9GdiF268/ijGYufA66nuPXpT+AGxXpQN/yVFaVN3Ji6F7zktRc3kKLC5OoHI+4h3nI2+gxekgqR8se+6Xi4f5RqYbpJRqB/yk4A/6DBGNGUYPRnPudxpui0I7Tfon5zi2fm93WYxeXORQ1GSGFr7dp1laf/ytQ9Ljt4LGc6iyJ5lI0tk1EhyXMIzWHkVA/ScOyhG3M5KfbpyqHTIGl1pfSMztU8J6deNBIQqEy7YoNnxbygkDv1O5p9dUxvsUgAjBW/tXoASKjH1SeP+EzYeZEmX1TRd35mJTiY5CTmw/OFINk+fTGplLIN3YeN9jxWg8tTmiIr2LsZA0Q2g4wjjqfamsYijOEyuZFaPqjG2Lwzup2PcfRuyDGYQEoayvlJWlkotn4bUEFU/wGAxsiULMwvQF1xAos8pv2qg8auyi35ox57aoz4rmMVQ56GNUkiBI7xBqG1BxW8cdZe+QVhQPxNClF0IYkbKuhr8Wiccs5QQ+Fnn3FeWzxYIOFE1gbtrPqdMBewpE/tOAtXOnDloXf6f9oHFSer05Dane4E+tBLao= X-Forefront-Antispam-Report-Untrusted: CIP:40.67.248.234;CTRY:IE;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:nebula.arm.com;PTR:InfoDomainNonexistent;CAT:NONE;SFS:(4636009)(36840700001)(46966006)(5660300002)(26005)(8676002)(508600001)(81166007)(83380400001)(47076005)(2616005)(36756003)(1076003)(8936002)(316002)(426003)(36860700001)(86362001)(70586007)(2906002)(7696005)(6666004)(4326008)(44832011)(82310400003)(6916009)(336012)(7416002)(70206006)(54906003)(186003)(356005)(36900700001);DIR:OUT;SFP:1101; X-MS-Exchange-Transport-CrossTenantHeadersStamped: AM6PR08MB4166 Return-Path: Sami.Mujawar@arm.com X-MS-Exchange-Transport-CrossTenantHeadersStripped: VE1EUR03FT064.eop-EUR03.prod.protection.outlook.com X-MS-Office365-Filtering-Correlation-Id-Prvs: 85a7471b-f7ed-4d82-f69e-08d98428aa44 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: snTytchdmA2KdBY7w5P8OL9JoEsAMeNCHIUOYI4DDxigiGQv7yHs5IqH1l4urMoa2FENr2QSre+ktW4xYZOCi0cyKU820GqbfM5V2DpqCFHSuhv9novIRI9KcBe6rIS1gc4fJAUuYd/4ybTt+Xogawq3uqmRQ6ggm4NU/Hf/M/SpaOKo5yznG+PJUiKXTJdwqqwokpKaFNEE4i4J9h/Nd2D+U928i+JzNlKJ4sv0WvvH4Oeb/G9PuRMdvVcnirLNc8S4uO0GHGxiJX2g0eQmUXR9J84TKpKUW/3Ss8OY2TTiAemKQD/xg74b2Z7PPDa/xo0i6ysDCZMNY1ZnsniOQyqFzHMsZlNh8z4DnDuACzCbBjGB9/ci1M/vIAeaKL8hztvFaMu/OMbZGlQKzRrIziXPsaDt+4g1I/xZYnx8hS+5eC0Wnwq0pYiHrTDFpxPmSWNUaMIIl/ZPPQ4KL0iRpwntx4H/n9CYq7BsmxaIBqWzJFoysa08qpBXzEpMErM+hsiwQH+UchI8wQe36ILPqO9UNSuprYr/UAbzE+RxZLbhLRJ27+RVCyH+j2AFXKbuLPhhHDGEj2qbvS66SxCNuuEDTSkRpkG1WvAOx7iaOQKBa929UN2Dp8PHPXDo1ZEhxQEScv+KWsat8wCHQpoGoaCuw2yZVKlV27sIGBCKJmQrokCgqb+poEaWU8Xt5R/ukRbPbldkERuITYI4xYScMMEnCwnf6NnI3SqoEaK7/uiwwpzFmLf6HatW/7GjnCrDL1msfunzAmZ7pNJshFdASiKp2UNt4I7RRuixx7/nE5WnDj537ig6lejaf0BUX5BAzKRbu6n7ZeKs1Njc7SW8og== X-Forefront-Antispam-Report: CIP:63.33.187.114;CTRY:IE;LANG:en;SCL:1;SRV:;IPV:CAL;SFV:NSPM;H:64aa7808-outbound-2.mta.getcheckrecipient.com;PTR:ec2-63-33-187-114.eu-west-1.compute.amazonaws.com;CAT:NONE;SFS:(4636009)(46966006)(36840700001)(6666004)(2616005)(26005)(7696005)(336012)(8936002)(186003)(54906003)(86362001)(1076003)(36756003)(81166007)(2906002)(426003)(8676002)(82310400003)(47076005)(36860700001)(83380400001)(4326008)(508600001)(70586007)(6916009)(70206006)(44832011)(5660300002)(316002);DIR:OUT;SFP:1101; X-OriginatorOrg: arm.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 30 Sep 2021 15:53:12.5491 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 75f19c24-82d2-4694-664c-08d9842a6883 X-MS-Exchange-CrossTenant-Id: f34e5979-57d9-4aaa-ad4d-b122a662184d X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=f34e5979-57d9-4aaa-ad4d-b122a662184d;Ip=[63.33.187.114];Helo=[64aa7808-outbound-2.mta.getcheckrecipient.com] X-MS-Exchange-CrossTenant-AuthSource: VE1EUR03FT064.eop-EUR03.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: DB6PR0801MB1719 Content-Type: text/plain Bugzilla: 3668 (https://bugzilla.tianocore.org/show_bug.cgi?id=3668) The NIST Special Publications 800-90A, 800-90B and 800-90C provide recommendations for random number generation. The NIST 800-90C, Recommendation for Random Bit Generator (RBG) Constructions, defines the GetEntropy() interface that is used to access the entropy source. The GetEntropy() interface is further used by Deterministic Random Bit Generators (DRBG) to generate random numbers. The True Random Number Generator (TRNG) library defines an interface to access the entropy source on a platform. Some platforms/architectures may provide access to the entropy using a firmware interface. In such cases the TRNG library shall be used to provide an abstraction. Signed-off-by: Sami Mujawar --- MdePkg/Include/Library/TrngLib.h | 123 ++++++++++++++++++++ MdePkg/MdePkg.dec | 7 +- 2 files changed, 129 insertions(+), 1 deletion(-) diff --git a/MdePkg/Include/Library/TrngLib.h b/MdePkg/Include/Library/TrngLib.h new file mode 100644 index 0000000000000000000000000000000000000000..8a02fe4bfe305a5249ceafceb4043b3f3df95c62 --- /dev/null +++ b/MdePkg/Include/Library/TrngLib.h @@ -0,0 +1,123 @@ +/** @file + TRNG interface library definitions. + + Copyright (c) 2021, Arm Limited. All rights reserved.
+ + SPDX-License-Identifier: BSD-2-Clause-Patent + + @par 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-90A Revision 1, June 2015, Recommendation + for Random Number Generation Using Deterministic Random Bit Generators. + (https://csrc.nist.gov/publications/detail/sp/800-90a/rev-1/final) + - [3] 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) + - [4] (Second Draft) NIST Special Publication 800-90C, Recommendation for + Random Bit Generator (RBG) Constructions. + (https://csrc.nist.gov/publications/detail/sp/800-90c/draft) + + @par Glossary: + - TRNG - True Random Number Generator +**/ +#ifndef TRNG_LIB_H_ +#define TRNG_LIB_H_ + +#include + +/** Get the version of the TRNG backend. + + A TRNG may be implemented by the system firmware, in which case this + function shall return the version of the TRNG backend. + The implementation must return NOT_SUPPORTED if a Back end is not present. + + @param [out] MajorRevision Major revision. + @param [out] MinorRevision Minor revision. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. + @retval EFI_UNSUPPORTED Backend not present. +**/ +EFI_STATUS +EFIAPI +GetTrngVersion ( + OUT UINT16 * CONST MajorRevision, + OUT UINT16 * CONST MinorRevision + ); + +/** Get the UUID of the 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 TRNG UUID is optional and if not implemented, EFI_UNSUPPORTED + shall be returned. + + Note: The caller must not rely on the returned UUID as a trustworthy TRNG + Back end identity + + @param [out] Guid UUID of the TRNG backend. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. + @retval EFI_UNSUPPORTED Function not implemented. +**/ +EFI_STATUS +EFIAPI +GetTrngUuid ( + OUT GUID * CONST Guid + ); + +/** Returns maximum number of entropy bits that can be returned in a single + call. + + @return Returns the maximum number of Entropy bits that can be returned + in a single call to GetEntropy(). + If this feature is not supported MAX_UINTN is returned. +**/ +UINTN +EFIAPI +GetTrngMaxSupportedEntropyBits ( + VOID + ); + +/** Returns N bits of conditioned entropy. + + See [3] 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. + + Note: In this implementation this function returns a status code instead + of a boolean value. + This is also compatible with the definition of Get_Entropy, see [4] + Section 7.4 Entropy Source Calls. + (status, entropy_bitstring) = Get_Entropy ( + requested_entropy, + max_length + ) + + @param [in] EntropyBits Number of entropy bits requested. + @param [out] Buffer Buffer to return the entropy bits. + @param [in] Buffersize Size of the Buffer in bytes. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. + @retval EFI_UNSUPPORTED Function not implemented. + @retval EFI_BAD_BUFFER_SIZE Buffer size is too small. + @retval EFI_NOT_READY No Entropy available. +**/ +EFI_STATUS +EFIAPI +GetEntropy ( + IN CONST UINTN EntropyBits, + OUT UINT8 * CONST Buffer, + IN CONST UINTN BufferSize + ); + +#endif // TRNG_LIB_H_ diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec index 9cdc915ebae94fa246c3883db5627819079add7e..492c3c3fd83e632dbf902bd8093b7d5e62597433 100644 --- a/MdePkg/MdePkg.dec +++ b/MdePkg/MdePkg.dec @@ -7,6 +7,7 @@ # Copyright (c) 2007 - 2021, Intel Corporation. All rights reserved.
# Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.
# (C) Copyright 2016 - 2021 Hewlett Packard Enterprise Development LP
+# Copyright (c) 2021, Arm Limited. All rights reserved.
# # SPDX-License-Identifier: BSD-2-Clause-Patent # @@ -267,11 +268,15 @@ [LibraryClasses] # RegisterFilterLib|Include/Library/RegisterFilterLib.h -[LibraryClasses.IA32, LibraryClasses.X64, LibraryClasses.AARCH64] +[LibraryClasses.IA32, LibraryClasses.X64, LibraryClasses.AARCH64, LibraryClasses.ARM] ## @libraryclass Provides services to generate random number. # RngLib|Include/Library/RngLib.h + ## @libraryclass Provides services to generate Entropy using a TRNG. + # + TrngLib|Include/Library/TrngLib.h + [LibraryClasses.IA32, LibraryClasses.X64] ## @libraryclass Abstracts both S/W SMI generation and detection. ## -- 'Guid(CE165669-3EF3-493F-B85D-6190EE5B9759)'