Add support for the RSA-PSS signature scheme as defined in RFC 8017
and required for TLS version 1.3.
Signature verification is deliberately implemented by first deriving
the salt value and then reconstructing the entire expected signature.
This is arguably inefficient since it involves two invocations of the
mask generation function when only one is required. However, this
implementation approach keeps the code size minimal (since there is no
need to implement separate verification logic), and makes it provably
impossible to accidentally omit a verification step (such as checking
the leading zero bits or the fixed 0x01 or 0xbc bytes). Since
signature verification is not a fast-path operation, the guaranteed
correctness is more valuable than a marginally faster execution.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Make the public key self-tests fully deterministic by temporarily
overriding the function used to obtain random data for RSA encryption.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
The EFI device path settings are currently registered as the
"netX.dhcp" settings block, in order that they will be automatically
overridden if a real DHCP configuration takes place. This does not
work as expected in an IPv6-only network, since the IPv6 configurator
will register "netX.ndp" rather than "netX.dhcp".
Fix by registering the EFI device path settings as either "netX.dhcp"
or "netX.ndp" based on the first address family encountered within the
device path.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
RFC 5246 defines the signature_algorithm extension values for TLS
version 1.2 as being tuples of {HashAlgorithm, SignatureAlgorithm}
pairs. RFC 8446 redefines the signature_algorithm extension values
for TLS version 1.3 in a backwards-compatible way as opaque 16-bit
SignatureScheme values, and RFC 8447 updates RFC 5246 to allow these
values to be used with TLS version 1.2.
Redefine our concept of a signature algorithm identifier to remove the
internal structure that no longer exists.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
The null crypto algorithms are intended to do nothing: the null digest
algorithm accepts all input and generates a zero-length digest, and
the null cipher algorithm simply copies the input unmodifed to the
output.
The null public-key algorithm currently does nothing successfully.
Unlike the null digest and cipher algorithms, the null public-key
algorithm's methods are never called.
Change the null public-key algorithm to fail all operations, thereby
allowing its methods to be used as stubs by algorithms such as ECDSA
that do not implement all of the possible public-key operations.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Add support for the HMAC-based Extract-and-Expand Key Derivation
Function (HKDF) as used in TLS version 1.3 and defined in RFC 5869.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Add support for a disk log partition console, using the same on-disk
structures as for the BIOS INT13 console.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Split out the generic portions of the INT13 disk log console support
to a separate file that can be shared between BIOS and UEFI platforms.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
For UEFI, the USB disk image is constructed from the built EFI binary
(e.g. bin-x86_64-efi/ipxe.efi) by genfsimg, which does not itself have
any way to access the build configuration. We therefore need a way to
annotate the binary such that genfsimg can determine whether or not to
include a log partition within the USB disk image.
The "OEM ID" and "OEM information" fields within the PE header can be
used for this, since they are easily accessed and serve no other
purpose. We define bit 0 of "OEM information" as a flag indicating
that a log partition should be included. If this bit is set, genfsimg
will create a log partition with a layout matching that of the BIOS
build (i.e. using partition 3 and at an offset of 16kB from the start
of the disk).
The PE header is constructed by elf2efi.c, which takes as an input the
linked ELF form of the binary. We use an ELF .note section to allow
any linked-in object to communicate the log partition request through
to elf2efi.c, which then populates the OEM information field
accordingly.
We choose to use the same field locations within the BIOS bzImage
header, since this allows genfsimg to use the same logic for both BIOS
and UEFI binaries. In a BIOS build, there is no external processing
equivalent to elf2efi.c, and so we construct the field value directly
using absolute symbols and explicit relocation records.
(Note that the bzImage header is relevant only when using genfsimg to
construct a combined BIOS/UEFI image. In the common case of building
a BIOS-only image such as bin/ipxe.usb, the partition table is
manually constructed by usbdisk.S and genfsimg is not involved.)
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Since October 2025, the Microsoft UEFI Signing Requirements have
included a clause stating that "submissions must contain a valid
signed SPDX SBOM in a custom '.sbom' PE section". A list of required
fields is provided, and a link is given to "the Microsoft SBOM tool to
aid SBOM generation". So far, so promising.
The Microsoft SBOM tool has no support for handling a .sbom PE
section. There is no published document that specifies what is
supposed to appear within this PE section. An educated guess is that
it should probably contain the raw JSON data in the same format that
the Microsoft SBOM tool produces.
The list of required fields does not map to identifiable fields within
the JSON. In particular:
- "file name / software"
This might be the top-level "name" field. It's hard to tell. The
SPDX SBOM specification is not particularly informative either: the
only definition it appears to give for "name" is "This field
identifies the name of an Element as designated by the creator",
which is a spectacularly useless definition.
- "software version / component generation (shim)"
This may refer to the "packages[].versionInfo" field. There is no
obvious relevance for the words "component", "generation", or
"shim". The proximity of "generation" and "shim" suggests that this
might be related in some way to the SBAT security generation, which
is absolutely not the same thing as the software version.
- "vendor / company name (this must exactly match the verified company
name in the submitter's EV certificate on the Microsoft HDC partner
center account)"
This is clearly written as though it has some significance for the
UEFI signing submission process. Unfortunately there is no obvious
map to any defined SBOM field. An educated guess is that this might
be referring to "packages[].supplier", since experiments show that
the Microsoft SBOM tool will fail validation unless this field is
present.
- "product-name"
This might also be the top-level "name" field. There is no
indication given as to how this might differ from "file name /
software".
- "OEM Name" and "OEM ID"
These seem to be terms made up on the spur of the moment. The
three-letter sequence "OEM" does not appear anywhere within the
codebase of the Microsoft SBOM tool.
In the absence of any meaningful specification, we choose not to
engage in good faith with this requirement. Instead, we construct a
best guess at the contents of a .sbom section that has some chance of
being accepted by the UEFI signing submission process. We assume that
anything that passes "sbom-tool validate" will probably be accepted,
with the only actual check being that the supplier name must match the
registered EV code signing certificate.
To anyone who actually cares about the arguably valuable benefits of
having a software bill of materials: please stop creating junk
requirements. If you want people to actually make the effort to
produce useful SBOM data, then make it clear what data you want.
Provide unambiguous specifications. Provide example files. Provide
tools that actually do the job they are claimed to do. Don't just
throw out another piece of "MUST HAS THING BECAUSE IS MORE SECURITY"
garbage and call it a day.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Most TPL manipulation is handled by efi_raise_tpl()/efi_restore_tpl()
pairs. The exceptions are the places where we need to temporarily
drop to a lower TPL in order to allow a timer interrupt to occur.
These currently assume that they are called only from code that is
already running at the internal TPL (generally TPL_CALLBACK). This
assumption is not always correct. In particular, the call from
_efi_start() to efi_driver_reconnect_all() takes place after the SNP
devices have been released and so will be running at the external TPL.
Create an efi_drop_tpl()/efi_undrop_tpl() pair to abstract away the
temporary lowering of the TPL, and ensure that the TPL is always
raised back to its original level rather than being unconditionally
raised to the internal TPL.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
TLS defines a mechanism for gracefully closing a connection via a
closure alert. We currently ignore this alert since it is a warning
rather than an error, and warnings are allowed to be ignored.
In almost all cases, a higher-level protocol such as HTTP will already
give us the information required to know when the connection should be
closed. In the very rare case of an HTTPS server that does not send a
Content-Length header and does not close the TCP connection, only the
closure alert indicates that the whole file has been retrieved.
Handle a received closure alert by gracefully closing the connection.
Reported-by: Tuomo Tanskanen <tuomo.tanskanen@est.tech>
Signed-off-by: Michael Brown <mcb30@ipxe.org>
It is unintuitive to have to include an "ifopen" at the start of an
autoexec.ipxe script. Provide a mechanism for upper-layer drivers to
mark a network device to be opened automatically upon registration,
and do so for the device to which the cached DHCPACK is applied.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
When searching for a shortcut key, search first from the currently
selected menu item and then from the start of the list.
This allows several ways for a shortcut key to be meaningfully used
multiple times within the same menu. For example, two sections may
have the same shortcut key:
item --key s --gap (S)ection 1
item ...
item ...
item --key s --gap (S)ection 2
item ...
With the above menu, repeated "s" keypresses would cycle through the
sections.
As another example, entries within different sections may have the
same shortcut keys. For example:
item --key d --gap (D)ebian
item --key s debst Debian (s)table release
item --key u debun Debian (u)nstable release
item --key f --gap (F)edora
item --key s fedst Fedora (s)table release
item --key u fedun Fedora (u)nstable release
With the above menu, a shortcut key sequence such as "f", "s" can be
used to select an entry within a specific section, avoiding the need
to choose shortcut keys that are globally unique within the menu.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Record the maximum size required when writing into a data transfer
buffer. This allows the maximum size to be determined even if
allocation fails (e.g. due to a fixed-size buffer or an out-of-memory
condition).
In the case of a fixed-size buffer (which may already be larger than
required), this allows the caller to determine the actual size used
for written data.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
TLS versions 1.2 and earlier define a 4-byte gmt_unix_time field as
part of the 32-byte ClientHello random data block, as a (minimal) form
of protection against a broken random number generator. iPXE has
never set this field to a correct value. Early versions had only
relative timers and so set this field to zero. Commit 5da7123 ("[tls]
Include current time within the client random bytes") did set this
field to the current time, but neglected to use the correct byte
ordering.
TLS version 1.3 (defined in RFC 8446) omits the gmt_unix_time field
completely and just defines the whole 32-byte value as random data.
Simplify the code by using the approach defined in RFC 8446.
Modified-by: Michael Brown <mcb30@ipxe.org>
Signed-off-by: Michael Brown <mcb30@ipxe.org>
RA contains MTU setting, this is especially needed in some networks
which don't have a a full 1500 MTU link to IPv6 internet. Mostly due
to some providers (such as Microsoft Azure) not having a working pMTUd
setup.
Signed-off-by: Christian I. Nilsson <nikize@gmail.com>
Modified-by: Michael Brown <mcb30@ipxe.org>
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Handle construction of the EFI, Linux, Xen, and VMBus driver build
rules via parserom.pl to ensure consistency. In particular, this
allows those drivers to appear in the DRIVERS_SECBOOT list used to
filter out non-permitted drivers in a Secure Boot build.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
The Xen netfront driver and the core architecture-independent files
such as xenstore.c and xenbus.c are already marked as permitted for
UEFI Secure Boot, but the x86-specific HVM driver (which attaches to
the PCI device and instantiates the Xen devices) is not.
Review the HVM-specific files and mark them as permitted for UEFI
Secure Boot.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Add DT_ROM() and DT_ID() macros following the pattern for PCI_ROM()
and PCI_ID(), to allow for the possibility of including devicetree
network devices within the "all-drivers" build of iPXE.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Add USB_ROM() and USB_ID() macros following the pattern for PCI_ROM()
and PCI_ID(), to allow for the possibility of including USB network
devices within the "all-drivers" build of iPXE.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
The original implementation in commit 943b300 ("[syslog] Add basic
support for encrypted syslog via TLS") was based on examples found in
the rsyslog documentation rather than on RFC 5425, and unfortunately
used the default syslog port number 514 rather than the syslog-tls
port number 6514 defined in the RFC.
Extend parsing of the syslog server name to allow for an optional port
number (in the relatively intuitive format "server[:port]"). Retain
the existing (and incorrect) default port number to avoid breaking
backwards compatibility with existing setups.
Reported-by: Christian Nilsson <nikize@gmail.com>
Signed-off-by: Michael Brown <mcb30@ipxe.org>
MS-CHAPv2 and the underlying DES algorithm are cryptographically
obsolete, but still relatively widely used. There is no impact to
UEFI Secure Boot from using these obsolete algorithms: the only
untrusted inputs are the username, password, and received network
packets, and all of these are thoroughly validated before use.
Review these files and mark them as permitted for UEFI Secure Boot.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Some older distributions (such as RHEL 8) provide their AArch64
kernels as gzip-compressed EFI binaries (with no self-decompressing
EFI stub present). We therefore enable support for gzip images by
default for arm64 EFI builds.
Review the files used to implement the gzip (and zlib) formats and
mark these as permitted for UEFI Secure Boot.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
An EFI build of iPXE does not directly make use of a flattened device
tree (FDT) itself, but may pass on a device tree that the user chose
to download using the "fdt" command.
Review the simple files used to implement the "fdt" command and mark
these as permitted for UEFI Secure Boot.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Update to the headers from the latest Xen stable release, and mark all
imported headers as permitted for UEFI Secure Boot.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
The dummy header files in include/bits/*.h are placeholders for
architectures that do not need to define any architecture-specific
functionality in these areas. Mark these trivial files as permitted
for UEFI Secure Boot.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Our long-standing policy for EFI platforms is that we support invoking
binary executables only via the LoadImage() and StartImage() boot
services calls, so that all security policy decisions are delegated to
the platform firmware.
Most binary executable formats that we support are BIOS-only and
cannot in any case be linked in to an EFI executable. The only
cross-platform format is the generic Linux kernel image format as used
for RISC-V (and potentially also for AArch64).
Mark all files associated with direct loading of a kernel binary as
explicitly forbidden for UEFI Secure Boot.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Enabling the GDB debugger functionality would provide an immediate and
trivial Secure Boot exploit. Mark all GDB-related files as explicitly
forbidden for UEFI Secure Boot.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
The Realtek driver and its dependencies are cleanly structured, easy
to review, directly maintained, and very well tested. Review these
files and mark them as permitted for UEFI Secure Boot.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Some past security reviews carried out for UEFI Secure Boot signing
submissions have covered specific drivers or functional areas of iPXE.
Mark all of the files comprising these areas as permitted for UEFI
Secure Boot.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Mark all files used in a standard build of bin-x86_64-efi/snponly.efi
as permitted for UEFI Secure Boot. These files represent the core
functionality of iPXE that is guaranteed to have been included in
every binary that was previously subject to a security review and
signed by Microsoft. It is therefore legitimate to assume that at
least these files have already been reviewed to the required standard
multiple times.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Not all files within the iPXE codebase are allowed to be included in
UEFI Secure Boot signed builds.
Following the pattern used by the existing FILE_LICENCE() macro and
licensing check: define a FILE_SECBOOT() macro that can be used to
declare a file as being permitted (or forbidden) in a UEFI Secure Boot
signed build, and a corresponding build target to perform the check.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Gather some basic statistics on TCP connections to allow out-of-order
packets and duplicate packets to be observed even in non-debug builds.
Report these statistics via the existing "ipstat" command, rather than
introducing a separate "tcpstat" command, on the basis that we do not
need the additional overhead of a separate command.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Add a fault-injection mechanism that allows an arbitrary delay
(configured via config/fault.h) to be added to any packets transmitted
via the neighbour resolution mechanism, as a way of reproducing
symptoms that occur only on high-latency connections such as a
satellite uplink.
The neighbour discovery mechanism is not a natural conceptual fit for
this artficial delay, since neighbour discovery has nothing to do with
transmit latency. However, the neighbour discovery mechanism happens
to already include a deferred transmission queue that can be (ab)used
to implement this artifical delay in a minimally intrusive way. In
particular, there is zero code size impact on a standard build with no
artificial delay configured.
Implementing the delay only for packets transmitted via neighbour
resolution has the side effect that broadcast packets (such as DHCP
and ARP) are unaffected. This is likely in practice to produce a
better emulation of a high-latency uplink scenario, where local
network traffic such as DHCP and ARP will complete quickly and only
the subsequent TCP/UDP traffic will experience delays.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Use the discovery protocol pointer field (rather than the running
state of the discovery timer) to determine whether or not neighbour
discovery is ongoing, as a precursor to allowing the timer to be
(ab)used for adding deliberate latency to transmitted packets.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
The API for neighbour_tx() allows for an explicit source link-layer
address, but this will be ignored if the packet is deferred for
transmission after completion of neighbour discovery. The network
device's own link-layer address will always be used when sending
neighbour discovery packets, and when sending any deferred packets
after discovery completes.
All callers pass in the network device's own link-layer address as the
source address anyway, and so this explicit source link-layer address
is never used for any meaningful purpose.
Simplify the neighbour_tx() API by removing the ability to pass in an
explicit source link-layer address.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Ensure that zero-length big integer literals are treated as containing
a zero value. Avoid tests on every big integer arithmetic operation
by ensuring that bigint_required_size() always returns a non-zero
value: the zero-length tests can therefore be restricted to only
bigint_init() and bigint_done().
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Add a public-key algorithm to the definition of the "ecPublicKey"
OID-identified algorithm, and move this definition to ecdsa.c to avoid
unconditionally dragging in ECDSA support.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
ECDSA requires the ability to add two arbitrary curve points, either
of which may legitimately be the point at infinity.
Update the API so that curves must choose an explicit affine
representation for the point at infinity, and provide a method to test
for this representation. Multiplication and addition will now allow
this representation to be provided as an input, and will not fail if
the result is the point at infinity. Callers must explicitly check
for the point at infinity where needed (e.g. after computing the ECDHE
shared secret curve point).
Signed-off-by: Michael Brown <mcb30@ipxe.org>
ECDSA signature values and private keys are fixed-length unsigned
integers modulo N (the group order of the elliptic curve) and are
therefore most naturally represented in ASN.1 using ASN1_OCTET_STRING.
Private key representations do use ASN1_OCTET_STRING, but signature
values tend to use ASN1_INTEGER, which adds no value but does ensure
that the encoding becomes variable-length and requires handling a
pointless extra zero byte if the MSB of the unsigned value happens to
be set.
RSA also makes use of ASN1_INTEGER for modulus and exponent values.
Generalise the existing rsa_parse_integer() to asn1_enter_unsigned()
to allow this code to be reused for ECDSA.
Signed-off-by: Michael Brown <mcb30@ipxe.org>
Michael Brown
Dexter Gerig
Christian I. Nilsson