Document Identifier: DSP0270

Date: 2020-04-11

Version: 1.3.0a

Redfish Host Interface Specification

Information for Work-in-Progress version:

IMPORTANT: This document is not a standard. It does not necessarily reflect the views of the DMTF or its members. Because this document is a Work in Progress, this document may still change, perhaps profoundly and without notice. This document is available for public review and comment until superseded.

Provide any comments through the DMTF Feedback Portal: http://www.dmtf.org/standards/feedback

Supersedes: 1.2.0

Document Class: Normative

Document Status: Work in Progress

Document Language: en-US

Document Confidentiality:

DMTF is a not-for-profit association of industry members dedicated to promoting enterprise and systems management and interoperability. Members and non-members may reproduce DMTF specifications and documents, provided that correct attribution is given. As DMTF specifications may be revised from time to time, the particular version and release date should always be noted.

Implementation of certain elements of this standard or proposed standard may be subject to third party patent rights, including provisional patent rights (herein "patent rights"). DMTF makes no representations to users of the standard as to the existence of such rights, and is not responsible to recognize, disclose, or identify any or all such third party patent right, owners or claimants, nor for any incomplete or inaccurate identification or disclosure of such rights, owners or claimants. DMTF shall have no liability to any party, in any manner or circumstance, under any legal theory whatsoever, for failure to recognize, disclose, or identify any such third party patent rights, or for such party's reliance on the standard or incorporation thereof in its product, protocols or testing procedures. DMTF shall have no liability to any party implementing such standard, whether such implementation is foreseeable or not, nor to any patent owner or claimant, and shall have no liability or responsibility for costs or losses incurred if a standard is withdrawn or modified after publication, and shall be indemnified and held harmless by any party implementing the standard from any and all claims of infringement by a patent owner for such implementations.

For information about patents held by third-parties which have notified the DMTF that, in their opinion, such patent may relate to or impact implementations of DMTF standards, visit http://www.dmtf.org/about/policies/disclosures.php.

This document's normative language is English. Translation into other languages is permitted.

CONTENTS

Foreword

The Redfish Host Interface Specification was prepared by the Redfish Forum of the DMTF.

DMTF is a not-for-profit association of industry members dedicated to promoting enterprise and systems management and interoperability. For information about the DMTF, see http://www.dmtf.org.

Acknowledgments

The DMTF acknowledges the following individuals for their contributions to this document:

1. Abstract

This specification defines functional requirements for Redfish Host Interfaces. In the context of this document, the term "Host Interface" refers to interfaces that can be used by software running on a computer system to access the Redfish Service that is used to manage that computer system.

The target audience for this specification is system manufacturers that are providing Redfish Host Interfaces within computer systems, system and component manufactures that are providing devices or firmware that include or support Redfish Host Interfaces, and system firmware and software writers that are creating software or firmware that uses Redfish Host Interfaces.

2. Normative references

The following referenced documents are indispensable for the application of this document. For dated or versioned references, only the edition cited (including any corrigenda or DMTF update versions) applies. For references without a date or version, the latest published edition of the referenced document (including any corrigenda or DMTF update versions) applies.

3. Terms and definitions

In this document, some terms have a specific meaning beyond the normal English meaning. Those terms are defined in this clause.

The terms "shall" ("required"), "shall not", "should" ("recommended"), "should not" ("not recommended"), "may", "need not" ("not required"), "can" and "cannot" in this document are to be interpreted as described in ISO/IEC Directives, Part 2, Clause 7. The terms in parenthesis are alternatives for the preceding term, for use in exceptional cases when the preceding term cannot be used for linguistic reasons. Note that ISO/IEC Directives, Part 2, Clause 7 specifies additional alternatives. Occurrences of such additional alternatives shall be interpreted in their normal English meaning.

The terms "clause", "subclause", "paragraph", and "annex" in this document are to be interpreted as described in ISO/IEC Directives, Part 2, Clause 6.

The terms "normative" and "informative" in this document are to be interpreted as described in ISO/IEC Directives, Part 2, Clause 3. In this document, clauses, subclauses, or annexes labeled "(informative)" do not contain normative content. Notes and examples are always informative elements.

The following additional terms are used in this document.

Term Definition
Host The Computer System that is managed by a Redfish Service
Host Software The software running on the Host Computer System, including Operating System and its Software components (such as drivers or applications), as well as preboot software such as UEFI or BIOS drivers and applications.
Redfish Service Also referred to as the "Service". The collection of functionality that implements the protocols, resources, and functions that deliver the interface defined by the Redfish API specification and its associated behaviors for one or more managed systems.
Redfish Service Entry Point Also referred to as "Service Entry Point". The interface through which a particular instance of a Redfish Service is accessed. A Redfish Service may have more than one Service Entry Point.
Redfish Manager Also referred to as "Manager". The entity that manages a Computer System and other peripherals through a Redfish Service.

4. Symbols and abbreviated terms

The following additional abbreviations are used in this document.

Term Definition
BIOS Basic I/O System. Name for system firmware typically used for initialization and launching the boot of an ISA (Industry Standard Architecture), aka 'x86' or 'PC', architecture-based computer system.
BSP Board Support Package. Name for system firmware typically used for initialization and launching the boot of Linux in a computer system that uses a non-ISA architecture, but may be used for booting other types of operating systems or runtime software.
SMBIOS System Management BIOS. Refers to DSP0134. Defines memory mapped tables, typically implemented by system firmware/BIOS and mapped into system firmware/BIOS memory space, that provide inventory and management information for the computer system.
UEFI Unified Extensible Firmware Interface. A modern firmware standard that defines the interfaces between hardware and Operating Systems in a Computer System. UEFI is supported on multiple processor architectures, including x86, x64, ia64, and AARCH64.
HI Host Interface
HTTP Hypertext Transfer Protocol
HTTPS Hypertext Transfer Protocol over TLS
IP Internet Protocol
IPMI Intelligent Platform Management Interface
NIC Network Interface Card
PCI Peripheral Component Interconnect
PCIe PCI Express
TCP Transmission Control Protocol
UUID Universally Unique Identifier

5. Introduction

Redfish is a flexible system management tool that can be successfully applied to various system architectures. One important architecture consists of one or more CPUs assigned to the system application (the Host CPUs) and a separate CPU or CPUs assigned solely to management including publishing the Redfish interface. In many management schemes, it is necessary to provide standardized Redfish-based communication between the Host CPU and the Redfish service in the Management unit. This communication is in addition to the Redfish services available via the external network. Implementation of the Redfish Host Interface is optional for the system designer. If provided, this interface may be used in both the preboot (firmware) stage and by drivers and applications within the Host Operating System and is designed to be available without use of external networking. This specification provides design details for several methods of Host-to-Service communication. Additional methods may be added in future revisions of this specification.

6. Scope

This specification is targeted to system manufacturers that are providing Redfish Host Interfaces within computer systems, system and component manufactures that are providing devices or firmware that include or support Redfish Host Interfaces, and system firmware and software writers that are creating software or firmware that uses Redfish Host Interfaces.

The specification covers Host accessible physical and logical communication paths and protocols that are used to access the Redfish Service that manages that Host.

The specification also defines certain supporting elements in the Host, such as SMBIOS extensions, that enable inventory and discovery functions.

The specification does not seek to place specific hardware implementation requirements; however, it does in some cases specify how hardware-specific interfaces are identified for Host Software (e.g., SMBIOS structures).

The specification defines connectivity between a Redfish Service and a Host. Any network routing or other connectivity beyond the Redfish Service or other networks is out of scope.

6.1. Goals

The following are the goals for the Redfish Host Interface:

7. Protocol details

A Redfish Host Interface shall support one of the following protocols:

7.1. Network Host Interface protocol details

Implementations that support the "Network Host Interface" protocol shall implement the following requirements:


DEPRECATED

DEPRECATED


8. SMBIOS support

Information in the SMBIOS structure shall allow Host Software to discover the Redfish Service Entry Point supported and to initialize the driver stack on the Host.

For Network Host Interfaces, the mechanism that clients should use to discover/obtain the Redfish Service Entry Point IP address shall also be described in the structure.

All SMBIOS structures referenced in this specification shall assume a little-endian ordering convention, unless explicitly specified otherwise, i.e., multi-byte numbers (WORD, DWORD, etc.) are stored with the low-order byte at the lowest address and the high-order byte at the highest address. Unless otherwise noted, strings in these structures follow "Text Strings" pattern described in the SMBIOS Specification.

8.1. SMBIOS Type 42 structure general layout

The SMBIOS Type 42 structure is used to describe a Management Controller Host Interface. It consists of standard SMBIOS entry information, followed by interface descriptors (which detail the physical interface to the Redfish Service), and protocol descriptors (which describe the supported payload encoding between the Host and Redfish Service). The following table shows the general format of the SMBIOS Type 42 structure:

 --------------------------
 Type 42 Header
 --------------------------
 Interface Specific Data
   - Device Description
   - (1 of 5 types)
 --------------------------
   Protocol Record Header
 --------------------------
   - Protocol Specific Data
 --------------------------

Further details about the SMBIOS Type 42 structure can be found in the SMBIOS Specification.

The remaining sections document how the SMBIOS Type 42 structure is defined for use by the Redfish Host Interface.

8.2. Table 1: SMBIOS Type 42 structure definition for Redfish Host Interfaces

The following describes the SMBIOS Management Controller Host Interface (Type 42) structure. Offset 00h-04h is the Type 42 Header. Starting at Offset 05h is the Interface-specific Data.

Offset Name Length Value Description
00h Type BYTE 42 Management Controller Host Interface structure indicator
01h Length BYTE Varies Length of the structure, a minimum of 09h
02h Handle WORD Varies
04h Interface Type BYTE ENUM Management Controller Interface Type. Network Host Interface is 40h.
05h Interface Specific Data Length (N) BYTE N Number of bytes (N) in the Interface Specific Data field. If 0, there is no Interface specific data.
06h Interface Specific Data N BYTEs Varies Management Controller Host Interface Data as specified by the Interface Type. See Table 2 below for Network Host Interface definitions.
06h+N Protocol Count BYTE X X number of Protocol Records for this Host Interface Type (typically 1).
07h+N Protocol Records M BYTEs Varies Protocol Records for each protocol supported. See Table 10 below record format.

8.3. Table 2: Interface Specific Data (for Interface Type 40h)

Interface Specific Data starts at offset 06h of the SMBIOS Type 42 structure. This table defines the Interface Specific data for Interface Type 40h. There are several types of Device Descriptors defined (see Table 3); however, only one may be used in specific Type 42 table.

Offset Name Length Value Description
00h Device Type BYTE ENUM The Device Type of the interface. The value of this field determines how the Device Descriptor Data is decoded. Table 3.
01h Device Descriptor Data N-1 BYTEs Varies The Device Descriptor Data formatted based on Device Type. See Table 4, Table 5, Table 6, Table 7, and Table 8.

8.3.1. Table 3: Device Type values

The following table defines the possible values for the Device Type field found in Table 2.

Value Description
02h USB Network Interface. See Table 4.
03h PCI/PCIe Network Interface. See Table 5.
04h USB Network Interface v2. See Table 6.
05h PCI/PCIe Network Interface v2. See Table 7.
80h-FFh OEM. See Table 8.
Others Reserved

8.3.2. Table 4: Device Descriptor Data for Device Type 02h (USB Network Interface)

The following table defines the Device Descriptor Data format for when the Device Type field is 02h, which indicates the device is a USB Network Interface.

Offset Name Length Value Description
00h Vendor ID WORD Varies The Vendor ID of the device, as read from the idVendor field of the USB descriptor (LSB first).
02h Product ID WORD Varies The Product ID of the device, as read from the idProduct field of the USB descriptor (LSB first).
04h Serial Number Descriptor Length BYTE Varies The number of bytes of the Serial Number, Serial Number Descriptor Type, and Serial Number Descriptor Length, as read from the iSerialNumber.bLength field of the USB descriptor. This field has a minimum value of 0x02.
05h Serial Number Descriptor Type BYTE 0x03 The Descriptor Type of the Serial Number, as read from the iSerialNumber.bDescriptorType field of the USB descriptor. This is always 0x03 to indicate that the descriptor is a string.
06h Serial Number Varies Varies The Serial Number of the device as a Unicode string without a NULL terminator, as read from the iSerialNumber.bString field of the USB descriptor. This string does not follow typical string patterns found elsewhere in SMBIOS definitions.

Examples type 02h descriptors:

8.3.3. Table 5: Device Descriptor Data for Device Type 03h (PCI/PCIe Network Interface)

The following table defines the Device Descriptor Data format for when the Device Type field is 03h, which indicates the device is a PCI/PCIe Network Interface.

Offset Name Length Value Description
00h Vendor ID WORD Varies The Vendor ID of the PCI/PCIe device as read from its PCI configuration space (LSB first).
02h Device ID WORD Varies The Device ID of the PCI/PCIe device as read from its PCI configuration space (LSB first).
04h Subsystem Vendor ID WORD Varies The Subsystem Vendor ID of the PCI/PCIe device as read from its PCI configuration space (LSB first).
06h Subsystem ID WORD Varies The Subsystem ID of the PCI/PCIe device as read from its PCI configuration space (LSB first).

Examples type 03h descriptors:

8.3.4. Table 6: Device Descriptor Data for Device Type 04h (USB Network Interface v2)

The following table defines the Device Descriptor Data format for when the Device Type field is 04h, which indicates the device is a USB Network Interface, version 2.

Offset Name Length Value Description
00h Length BYTE Varies

Length of the structure, including Device Type and Length fields. Length dependent on version of the Redfish Host Interface Specification supported:

  • 11h for 1.3.
  • 0Dh for 1.2 and older.
01h Vendor ID WORD Varies The Vendor ID of the device, as read from the idVendor field of the USB descriptor (LSB first).
03h Product ID WORD Varies The Product ID of the device, as read from the idProduct field of the USB descriptor (LSB first).
05h Serial Number BYTE STRING The string number for the Serial Number of the device. The string data is read from the iSerialNumber.bDescriptorType field of the USB descriptor, and is converted from Unicode to ASCII and is NULL terminated. See "Text Strings" in the SMBIOS Specification for how this field is constructed.
06h MAC Address 6 BYTEs Varies The MAC address of the USB network device (most significant octet first).
0Ch Device Characteristics WORD Varies Additional characteristics for the device. See Table 9.
0Eh Credential Bootstrapping Handle WORD Varies Handle of the interface to be used for credential bootstrapping via IPMI commands. The value is 0xFFFF if not supported.

8.3.5. Table 7: Device Descriptor Data for Device Type 05h (PCI/PCIe Network Interface v2)

The following table defines the Device Descriptor Data format for when the Device Type field is 05h, which indicates the device is a PCI/PCIe Network Interface, version 2.

Offset Name Length Value Description
00h Length BYTE Varies

Length of the structure, including Device Type and Length fields. Length dependent on version of the Redfish Host Interface Specification supported:

  • 18h for 1.3.
  • 14h for 1.2 and older.
01h Vendor ID WORD Varies The Vendor ID of the PCI/PCIe device as read from its PCI configuration space (LSB first).
03h Device ID WORD Varies The Device ID of the PCI/PCIe device as read from its PCI configuration space (LSB first).
05h Subsystem Vendor ID WORD Varies The Subsystem Vendor ID of the PCI/PCIe device as read from its PCI configuration space (LSB first).
07h Subsystem ID WORD Varies The Subsystem ID of the PCI/PCIe device as read from its PCI configuration space (LSB first).
09h MAC Address 6 BYTEs Varies The MAC address of the PCI/PCIe network device (most significant octet first).
0Fh Segment Group Number WORD Varies The Segment Group Number of the PCI/PCIe device as defined in the PCI Firmware Specification. The value is 0 for a single-segment topology.
11h Bus Number BYTE Varies The Bus Number of the PCI/PCIe device.
12h Device/Function Number BYTE Varies The Device/Function Number of the PCI/PCIe device.
Bits 7:3 - Device Number
Bits 2:0 - Function Number.
13h Device Characteristics WORD Varies Additional characteristics for the device. See Table 9.
15h Credential Bootstrapping Handle WORD Varies Handle of the interface to be used for credential bootstrapping via IPMI commands. The value is 0xFFFF if not supported.

8.3.6. Table 8: Device Descriptor Data for Device Types 80h-FFh (OEM)

The following table defines the Device Descriptor Data format for when the Device Type field is 80h-FFh, which indicates the device is an OEM device.

Offset Name Length Value Description
00h Vendor IANA 4 BYTEs Varies The IANA code for the vendor (MSB first).
04h Vendor Data Varies Varies OEM defined data.

8.3.7. Table 9: Device Characteristics

The following table defines the bit field for the Device Characteristics field found in Table 6 and Table 7.

Word Bit Position Meaning
Bit 0 Credential bootstrapping via IPMI commands is supported.
Bits 1:15 Reserved.

8.4. Table 10: Protocol Records data format

Protocol Records start at offset 07h+N of the SMBIOS Type 42 structure. The following table defines the general Protocol Record layout specific data for Redfish over IP protocol:

Offset Name Length Value Description
00h Protocol Type BYTE ENUM The Protocol Type. "Redfish over IP" is 04h.
01h Protocol Type Specific Data Length BYTE P The length of the Protocol Specific Record Data field.
02h Protocol Specific Record Data P BYTEs Varies The data for the protocol as defined by the Protocol Type. See Table 11 for "Redfish over IP" protocol.

8.4.1. Table 11: "Redfish over IP" Protocol Specific Record Data

Protocol Specific Record Data starts at offset 02h of the Protocol Record structure. The following table defines the protocol specific data for the "Redfish Over IP" protocol:

Offset Name Length Value Description
00h Service UUID 16 BYTEs Varies Same as Redfish Service UUID in Redfish Service Root resource; set to all 0s if the UUID is not supported or unknown.
10h Host IP Assignment Type BYTE ENUM The method for how the host IP address is assigned. See Table 12.
11h Host IP Address Format BYTE ENUM The format of the Host IP Address. See Table 13.
12h Host IP Address 16 BYTEs Varies Used for Static and AutoConfigure.
For IPv4, use the first 4 Bytes and zero fill the remaining bytes.
22h Host IP Mask 16 BYTEs Varies Used for Static and AutoConfigure.
For IPv4, use the first 4 Bytes and zero fill the remaining bytes.
32h Redfish Service IP Discovery Type BYTE ENUM The method for how the Redfish Service IP address is discovered. See Table 12.
33h Redfish Service IP Address Format BYTE ENUM The format of the Redfish Service IP Address. See Table 13.
34h Redfish Service IP Address 16 BYTEs Varies Used for Static and AutoConfigure.
For IPv4, use the first 4 Bytes and zero fill the remaining bytes.
44h Redfish Service IP Mask 16 BYTEs Varies Used for Static and AutoConfigure.
For IPv4, use the first 4 Bytes and zero fill the remaining bytes.
54h Redfish Service IP Port WORD Varies Used for Static and AutoConfigure.
56h Redfish Service VLAN ID DWORD Varies Used for Static and AutoConfigure.
5Ah Redfish Service Hostname Length BYTE Varies The length in bytes of the "Redfish Service Hostname" field, including any NULL characters in the field.
5Bh Redfish Service Hostname Varies Varies Hostname of Redfish Service; this string may end with zero or more NULL characters. This string does not follow typical string patterns found elsewhere in SMBIOS definitions.

The UUID is 128 bits long. Its format is described in RFC4122. Although RFC4122 recommends network byte order for all fields, the PC industry (including the ACPI, UEFI, and Microsoft specifications) has consistently used little-endian byte encoding for the first three fields: time_low, time_mid, time_hi_and_version. The same encoding, also known as wire format, should also be used for the SMBIOS representation of the UUID.

In the above table, the fields "Host IP Address", "Host IP Mask", "Redfish Service IP Address", and "Redfish Service IP Mask" shall be stored in network byte order.

8.4.2. Table 12: Assignment/Discovery Type values

The following table defines the possible values for the Assignment Type and Discovery Type fields found in Table 11.

Value Description
00h Unknown
01h Static
02h DHCP
03h AutoConfigure
04h HostSelected
Others Reserved

8.4.3. Table 13: IP Address Format values

The following table defines the possible values for the Host IP Address Format and Redfish Service IP Address Format fields found in Table 11.

Value Description
00h Unknown
01h IPv4
02h IPv6
Others Reserved

8.5. Multiple Protocol Records

The SMBIOS Type 42 structure allows for multiple Protocol Records to be specified within a given Type 42 entry. For Redfish, this could be used to describe both IPv4 and IPv6 information for a single Redfish Service. However, due to the size of the Redfish over IP Protocol, it is likely not possible to use two Protocol Records in a single Type 42 entry without going beyond the limit of the Length field of the Type 42 structure found at offset 01h. If multiple Protocol Records are needed to describe a single Redfish Service, there should be a Type 42 entry for each of the Protocol Records. The Interface Specific Data portion of each Type 42 entry shall be identical if they map to the same Redfish Service. Clients should interpret multiple Type 42 entries with identical Interface Specific Data as a single Redfish Service with multiple protocols.

This methodology also allows for multiple Redfish Services to be described by multiple Type 42 entries. Clients should interpret Type 42 entries with different Interface Specific Data as different Redfish Services.

9. Credential bootstrapping via IPMI commands

Services may support provisioning a temporary account for the host interface using IPMI commands. This is to allow a host with no initial knowledge of the Redfish interface to create an initial account from which it can create a permanent account for the life of the system.

Services that support credential bootstrapping via IPMI commands shall:

9.1. IPMI command definitions

The following clause defines IPMI commands added to the "Group Extension" NetFn (2Ch, 2Dh). The defining body code for Redfish is 52h.

The service shall implement the IPMI commands defined in this clause.

9.1.1. Get Manager Certificate Fingerprint (NetFn 2Ch, Command 01h)

This command is used to get the fingerprint for the manager's TLS certificate for the host interface. In most cases, the manager will only have one certificate available. Clients should use the response data from this command when connecting over the host interface to verify the service's certificate matches.

Request data:

Byte Data field
1 Group extension identification (52h).
2 Certificate number (1 based).

Response data:

Byte Data field
1

Completion code:

  • 00h: Command completed normally.
  • 80h: Credential bootstrapping via IPMI commands is disabled.
  • CBh: Certificate number is invalid.
2 Group extension identification (52h).
3

Fingerprint hash algorithm:

  • 01h: SHA-256. The length of the fingerprint will be 32 bytes.
  • Others: Reserved.
4:N Fingerprint of the manager's TLS certificate.

9.1.2. Get Bootstrap Account Credentials (NetFn 2Ch, Command 02h)

This command is used to get the user name and password of the bootstrap account. When the manager receives this command, it shall generate a new user name and password for the bootstrap account, store the credentials in a manner consistent with other Redfish accounts, and provide the credentials in the response data to the host. The manager should randomly generate the user name, and shall randomly generate the password.

The user name and password shall:

Request data:

Byte Data field
1 Group extension identification (52h).

Response data:

Byte Data field
1

Completion code:

  • 00h: Command completed normally.
  • 80h: Credential bootstrapping via IPMI commands is disabled.
2 Group extension identification (52h).
3:18 The user name as a UTF-8 string. Strings with fewer than 16 characters are terminated with a null (00h) character and 00h padded to 16 bytes.
19:34 The password as a UTF-8 string. Strings with fewer than 16 characters are terminated with a null (00h) character and 00h padded to 16 bytes.

9.2. Account life cycle

The bootstrap account shall be added to the manager's account collection and enabled when the Get Bootstrap Account Credentials command haa been issued and responded with a completion code of 00h.

No more than one bootstrap account shall be provisioned at a given time. If the Get Bootstrap Account Credentials command is sent subsequent times, the one provisioned account shall be updated based on the newly generated credentials.

The bootstrap account shall be usable only on the host interface.

Services shall delete the bootstrap account:

9.3. Recommendations for hosts

Anyone with root access to the host is able to make use of this mechanism for provisioning an account. However, it is recommended that this mechanism only be used during initial provisioning of a host. The overall workflow for using this interface is recommended to be:

  1. Use this mechanism to create a bootstrap account.
  2. Using the bootstrap account, create a permanent account for the host in the manager account collection found in the account service.
  3. Set the Enabled property within the CredentialBootstrapping property of the host interface resource to false.

10. Delivery of credentials via UEFI runtime variables

DEPRECATED: This entire clause has been deprecated in favor of other credential negotiation mechanisms described in this specification, such as credential bootstrapping via IPMI commands.


DEPRECATED

This clause defines an optional mechanism for automatically generating and sending credentials to the Host OS kernel and/or firmware by using UEFI runtime variables. Services that implement the kernel authentication mechanism shall comply with the following subclauses:

10.1. Credential generation and management for use by firmware and OS kernel

Opening a Redfish session on the Host Interface may be accomplished by use of any authorized Redfish credentials consisting of a valid username and password. However in some situations, it may be difficult to pre-provision the system with valid Redfish credentials for use by OS and firmware clients of Redfish. Examples of this include (a) early provisioning of new systems and (b) systems where firmware does not have secure storage to hide the credentials.

To provide for situations of this type, systems supporting the Redfish Service may optionally be configured to provide temporary logon credentials for use by Firmware Preboot elements and/or OS. If implemented, the credentials shall follow these requirements:

10.2. Security considerations for protecting auto-generated credentials

It is recommended that system designers protect the credentials from unauthorized access. The use of UEFI Secure Boot to protect access to credentials is recommended. Because of the difficulty of defining a security procedure for Legacy-booting OS, delivery of credentials to Legacy OS is not described by this specification and any Legacy OS support for this feature is OEM-specific.

The system OS is provided with a method of disabling further retrieval of the credentials after initial authorized retrieval. System designers are encouraged to implement such a scheme of retrieve, store, and disable to avoid unauthorized reading of the credential variables

10.3. UEFI implementation

Implementations that present a Redfish Host Interface for use by system firmware and OS shall use the UEFI Variables defined in this section to deliver credentials for the Redfish Host Interface.

The design of this delivery mechanism is compatible with any UEFI version starting with 2.3.1. Refer to the specifications available at www.uefi.org for details on using the UEFI variable calls described here.

10.3.1. Prototype

#define EFI_REDFISH_INFORMATION_GUID \
    {0x16faa37e, 0x4b6a, 0x4891, {0x90, 0x28, 0x24, 0x2d, 0xe6, 0x5a, 0x3b, 0x70 }}
#define EFI_REDFISH_INFORMATION_INDICATIONS         L"RedfishIndications"
#define EFI_REDFISH_INFORMATION_FW_CREDENTIALS      L"RedfishFWCredentials"
#define EFI_REDFISH_INFORMATION_OS_CREDENTIALS      L"RedfishOSCredentials"
#define EFI_REDFISH_INDICATIONS_FW_CREDENTIALS      0x00000001
#define EFI_REDFISH_INDICATIONS_OS_CREDENTIALS      0x00000002

10.3.3. Description

This GUID and these variable names are used when calling the UEFI Runtime Service GetVariable(). See the UEFI Specification for details on use of this interface. As described below, the SetVariable() interface can be used to disable further access to the credential information.

The variables defined in this section have the following attributes:

The variable EFI_REDFISH_INFORMATION_INDICATIONS shall return a 32-bit value, and provides information if any credentials are provided for the Host Software use. The bits defined with this variable shall be interpreted as follows:

When the Redfish implementation provides credentials for firmware use, the variable EFI_REDFISH_INFORMATION_FW_CREDENTIALS shall contain a UTF-8 character array formatted as described in the next clause. If this session is not available as defined by current system policy, this variable shall return EFI_NOT_FOUND.

When the Redfish implementation provides credentials for OS use, the variable EFI_REDFISH_INFORMATION_OS_CREDENTIALS a UTF-8 character array formatted as described in the next clause. If these credentials are not available as defined by current system policy, this variable shall return EFI_NOT_FOUND.

The password contained in these variables shall be recalculated so as to be unique and not easily predicted on each boot.

If the variables EFI_REDFISH_INFORMATION_FW_CREDENTIALS or EFI_REDFISH_INFORMATION_OS_CREDENTIALS are accessed using the SetVariable() function with a DataSize of zero, the variable contents shall be hidden until the next system restart and not be available for retrieval by future GetVariable() calls. After such SetVariable() access any GetVariable() attempt shall return EFI_NOT_FOUND error. Calls to SetVariable() with nonzero DataSize shall be processed as if DataSize is zero.

10.3.4. Variable format

The UEFI variables for delivery of temporary credentials shall contain an array of UTF-8 characters in the format Username:Password where the : character shall act as separator. The final byte of the array shall be 0x00 as terminator and the size of the variable shall be length of Username plus length of Password plus 2. Characters shall be chosen from the set elsewhere defined as legal for Redfish Username and Password and neither field may contain the : character.

For convenience when identifying the auto-generated credentials when active and for the purpose of editing permissions, the following Username strings shall be used:

Usage Username
Default Firmware Auto Username HostAutoFW
Default OS Auto Username HostAutoOS

DEPRECATED


11. ANNEX A (informative)

11.1. Change log

Version Date Description
1.3.0a 2020-04-11 Added clauses for bootstrapping credentials via IPMI.
Deprecated credential reporting via UEFI variables.
Extended USB Network Interface v2 and PCI/PCIe Network Interface v2 descriptors to include Device Characteristics and Credential Bootstrapping Handle fields.
1.2.0 2019-10-11 Added clause to allow for multiple SMBIOS Type 42 structures in order to specify multiple Protocol Record.
1.1.0 2019-05-16 Clarified the byte ordering in SMBIOS structures.
Clarified the data shown in the Device Descriptor Table.
Clarified the format of the Host Name field.
Added example device descriptors.
Added version 2 of the USB and PCI/PCI-e device descriptors.
Clarified the format of the UUID.
1.0.1 2017-12-11 Errata release. Numerous terminology clarifications and typographical corrections.
Terminology for 'host', 'manager' and 'service' were edited for consistency.
Added additional wording about the SMBIOS Type 42 structure to describe its purpose.
Added references to the UEFI Specification.
Clarified byte ordering of IPv4 and IPv6 addresses in the SMBIOS Type 42 structure.
Added missing case for what to use for the UUID in the SMBIOS Type 42 structure if it is unknown or not supported.
1.0.0 2016-12-30 Initial release.