HALF ECHO LEARN / REFERENCE COLLECTION
v262.2src/ukify/ukify.py
Git blob: e7f98667a80d75db00722f2cef852de5533d04f1
Lines 2001–2747 of 2,747
# It'd be nice if argparse exported this, but I don't see that in the API
if self.dest:
return self.dest
return self._names()[0].lstrip('-').replace('-', '_')
def add_to(self, parser: argparse.ArgumentParser) -> None:
kwargs = {
key: val
for key in dataclasses.asdict(self)
if (key not in ('name', 'config_key', 'config_push') and (val := getattr(self, key)) is not None)
}
args = self._names()
parser.add_argument(*args, **kwargs)
def parse_value(self, s: str) -> Any:
if self.action == argparse.BooleanOptionalAction:
# We need to handle this case separately: the options are called
# --foo and --no-foo, and no argument is parsed. But in the config
# file, we have Foo=yes or Foo=no.
return self.parse_boolean(s)
elif self.type:
return self.type(s)
return s
def apply_config(
self,
namespace: argparse.Namespace,
section: str,
group: Optional[str],
key: str,
value: Any,
) -> None:
assert f'{section}/{key}' == self.config_key
dest = self.argparse_dest()
# This is a bit ugly, but --initrd and --devicetree-auto are the only options
# with multiple args on the command line and a space-separated list in the
# config file.
if self.name in ['--initrd', '--devicetree-auto']:
value = [self.parse_value(v) for v in value.split()]
else:
value = self.parse_value(value)
self.config_push(namespace, group, dest, value)
def config_example(self) -> tuple[Optional[str], Optional[str], Optional[str]]:
if not self.config_key:
return None, None, None
section_name, key = self.config_key.split('/', 1)
if section_name.endswith(':'):
section_name += 'NAME'
if self.choices:
value = '|'.join(self.choices)
else:
value = self.metavar or self.argparse_dest().upper()
return (section_name, key, value)
VERBS = ('build', 'genkey', 'inspect')
CONFIG_ITEMS = [
ConfigItem(
'positional',
metavar='VERB',
nargs='*',
help=argparse.SUPPRESS,
),
ConfigItem(
'--version',
action='version',
version=f'ukify {__version__}',
),
ConfigItem(
'--summary',
help='print parsed config and exit',
action='store_true',
),
ConfigItem(
('--config', '-c'),
metavar='PATH',
type=Path,
help='configuration file',
),
ConfigItem(
'--linux',
type=Path,
help='vmlinuz file [.linux section]',
config_key='UKI/Linux',
),
ConfigItem(
'--os-release',
metavar='TEXT|@PATH',
help='path to os-release file [.osrel section]',
config_key='UKI/OSRelease',
),
ConfigItem(
'--cmdline',
metavar='TEXT|@PATH',
help='kernel command line [.cmdline section]',
config_key='UKI/Cmdline',
),
ConfigItem(
'--initrd',
metavar='INITRD',
type=Path,
action='append',
help='initrd file [part of .initrd section]',
config_key='UKI/Initrd',
config_push=ConfigItem.config_list_prepend,
),
ConfigItem(
'--efifw',
metavar='DIR',
type=Path,
action='append',
default=[],
help='Directory with efi firmware binary file [.efifw section]',
config_key='UKI/Firmware',
config_push=ConfigItem.config_list_prepend,
),
ConfigItem(
'--microcode',
metavar='UCODE',
type=Path,
help='microcode file [.ucode section]',
config_key='UKI/Microcode',
),
ConfigItem(
'--splash',
metavar='BMP',
type=Path,
help='splash image bitmap file [.splash section]',
config_key='UKI/Splash',
),
ConfigItem(
'--devicetree',
metavar='PATH',
type=Path,
help='Device Tree file [.dtb section]',
config_key='UKI/DeviceTree',
),
ConfigItem(
'--devicetree-auto',
metavar='PATH',
type=Path,
action='append',
help='DeviceTree file for automatic selection [.dtbauto section]',
default=[],
config_key='UKI/DeviceTreeAuto',
config_push=ConfigItem.config_list_prepend,
),
ConfigItem(
'--hwids',
metavar='DIR',
help='Directory with HWID text files [.hwids section]',
config_key='UKI/HWIDs',
),
ConfigItem(
'--uname',
metavar='VERSION',
help='"uname -r" information [.uname section]',
config_key='UKI/Uname',
),
ConfigItem(
'--sbat',
metavar='TEXT|@PATH',
help='SBAT policy [.sbat section]',
default=[],
action='append',
config_key='UKI/SBAT',
config_push=ConfigItem.config_list_prepend,
),
ConfigItem(
'--pcrpkey',
metavar='KEY',
type=Path,
help='embedded public key to seal secrets to [.pcrpkey section]',
config_key='UKI/PCRPKey',
),
ConfigItem(
'--section',
dest='sections',
metavar='NAME:TEXT|@PATH',
action='append',
default=[],
help='section as name and contents [NAME section] or section to print',
),
ConfigItem(
'--profile',
metavar='TEST|@PATH',
help='Profile information [.profile section]',
config_key='UKI/Profile',
),
ConfigItem(
'--join-profile',
dest='join_profiles',
metavar='PATH',
action='append',
default=[],
help='A PE binary containing an additional profile to add to the UKI',
),
ConfigItem(
'--sign-profile',
dest='sign_profiles',
metavar='ID',
action='append',
default=[],
help='Which profiles to sign expected PCR measurements for',
),
ConfigItem(
'--pcrsig',
metavar='TEST|@PATH',
help='Signed PCR policy JSON [.pcrsig section] to append to an existing UKI',
config_key='UKI/PCRSig',
),
ConfigItem(
'--join-pcrsig',
metavar='PATH',
help='A PE binary containing a UKI without a .pcrsig to join with --pcrsig',
),
ConfigItem(
'--efi-arch',
metavar='ARCH',
choices=('ia32', 'x64', 'arm', 'aa64', 'riscv32', 'riscv64', 'loongarch32', 'loongarch64'),
help='target EFI architecture',
config_key='UKI/EFIArch',
),
ConfigItem(
'--stub',
type=Path,
help='path to the sd-stub file [.text,.data,… sections]',
config_key='UKI/Stub',
),
ConfigItem(
'--pcr-banks',
metavar='BANK…',
type=parse_banks,
config_key='UKI/PCRBanks',
),
ConfigItem(
'--signing-engine',
metavar='ENGINE',
help='OpenSSL engine to use for signing',
config_key='UKI/SigningEngine',
),
ConfigItem(
'--signing-provider',
metavar='PROVIDER',
help='OpenSSL provider to use for signing',
config_key='UKI/SigningProvider',
),
ConfigItem(
'--certificate-provider',
metavar='PROVIDER',
help='OpenSSL provider to load certificate from',
config_key='UKI/CertificateProvider',
),
ConfigItem(
'--signtool',
choices=('sbsign', 'pesign', 'systemd-sbsign'),
dest='signtool',
help=(
'whether to use sbsign or pesign. It will also be inferred by the other '
'parameters given: when using --secureboot-{private-key/certificate}, sbsign '
'will be used, otherwise pesign will be used'
),
config_key='UKI/SecureBootSigningTool',
),
ConfigItem(
'--secureboot-private-key',
dest='sb_key',
help='required by --signtool=sbsign|systemd-sbsign. Path to key file or engine/provider designation for SB signing',
config_key='UKI/SecureBootPrivateKey',
),
ConfigItem(
'--secureboot-certificate',
dest='sb_cert',
help=(
'required by --signtool=sbsign. sbsign needs a path to certificate file or engine-specific designation for SB signing'
),
config_key='UKI/SecureBootCertificate',
),
ConfigItem(
'--secureboot-certificate-common-name',
metavar='CN',
dest='sb_cert_common_name',
help="common name of a certificate created by 'genkey'",
config_key='UKI/SecureBootCertificateCommonName',
),
ConfigItem(
'--secureboot-certificate-dir',
dest='sb_certdir',
default='/etc/pki/pesign',
help=(
'required by --signtool=pesign. Path to nss certificate database directory for PE signing. Default is /etc/pki/pesign'
),
config_key='UKI/SecureBootCertificateDir',
config_push=ConfigItem.config_set,
),
ConfigItem(
'--secureboot-certificate-name',
dest='sb_cert_name',
help=(
'required by --signtool=pesign. pesign needs a certificate nickname of nss certificate database entry to use for PE signing'
),
config_key='UKI/SecureBootCertificateName',
),
ConfigItem(
'--secureboot-certificate-validity',
metavar='DAYS',
type=int,
dest='sb_cert_validity',
default=365 * 10,
help="period of validity (in days) for a certificate created by 'genkey'",
config_key='UKI/SecureBootCertificateValidity',
config_push=ConfigItem.config_set,
),
ConfigItem(
'--sign-kernel',
action=argparse.BooleanOptionalAction,
help='Sign the embedded kernel',
config_key='UKI/SignKernel',
),
ConfigItem(
'--sign-initrd-pcrs',
action=argparse.BooleanOptionalAction,
help='additionally sign PCR policies that can only be satisfied from the initrd',
config_key='UKI/SignInitrdPCRs',
),
ConfigItem(
'--pcr-private-key',
dest='pcr_private_keys',
action='append',
help='private part of the keypair or engine/provider designation for signing PCR signatures',
config_key='PCRSignature:/PCRPrivateKey',
config_push=ConfigItem.config_set_group,
),
ConfigItem(
'--pcr-public-key',
dest='pcr_public_keys',
metavar='PATH',
action='append',
help='public part of the keypair or engine/provider designation for signing PCR signatures',
config_key='PCRSignature:/PCRPublicKey',
config_push=ConfigItem.config_set_group,
),
ConfigItem(
'--pcr-certificate',
dest='pcr_certificates',
metavar='PATH',
action='append',
help='certificate part of the keypair or engine/provider designation for signing PCR signatures',
config_key='PCRSignature:/PCRCertificate',
config_push=ConfigItem.config_set_group,
),
ConfigItem(
'--phases',
dest='phase_path_groups',
metavar='PHASE-PATH…',
type=parse_phase_paths,
action='append',
help='phase-paths to create signatures for',
config_key='PCRSignature:/Phases',
config_push=ConfigItem.config_set_group,
),
ConfigItem(
'--policyref',
dest='policyrefs',
metavar='STRING',
action='append',
help='policy references to bind signatures to',
config_key='PCRSignature:/PolicyRef',
config_push=ConfigItem.config_set_group,
),
ConfigItem(
'--tools',
type=Path,
action='append',
help='Directories to search for tools (systemd-measure, …)',
),
ConfigItem(
('--output', '-o'),
type=Path,
help='output file path',
),
ConfigItem(
'--measure',
action=argparse.BooleanOptionalAction,
help='print systemd-measure output for the UKI',
),
ConfigItem(
'--policy-digest',
action=argparse.BooleanOptionalAction,
help='print systemd-measure policy digests for the UKI',
),
ConfigItem(
'--json',
choices=('pretty', 'short', 'off'),
default='off',
help='generate JSON output',
),
ConfigItem(
'-j',
dest='json',
action='store_const',
const='pretty',
help='equivalent to --json=pretty',
),
ConfigItem(
'--all',
help='print all sections',
action='store_true',
),
]
CONFIGFILE_ITEMS = {item.config_key: item for item in CONFIG_ITEMS if item.config_key}
def apply_config(namespace: argparse.Namespace, filename: Union[str, Path, None] = None) -> None:
if filename is None:
if namespace.config:
# Config set by the user, use that.
filename = namespace.config
print(f'Using config file: {filename}', file=sys.stderr)
else:
# Try to look for a config file then use the first one found.
for config_dir in DEFAULT_CONFIG_DIRS:
filename = Path(config_dir) / DEFAULT_CONFIG_FILE
if filename.is_file():
# Found a config file, use it.
print(f'Using found config file: {filename}', file=sys.stderr)
break
else:
# No config file specified or found, nothing to do.
return
# Fill in ._groups based on --pcr-public-key=, --pcr-private-key=, and --phases=.
assert '_groups' not in namespace
n_pcr_priv = len(namespace.pcr_private_keys or ())
namespace._groups = list(range(n_pcr_priv)) # pylint: disable=protected-access
cp = configparser.ConfigParser(
comment_prefixes='#',
inline_comment_prefixes='#',
delimiters='=',
empty_lines_in_values=False,
interpolation=None,
strict=False,
)
# Do not make keys lowercase
cp.optionxform = lambda option: option # type: ignore
# The API is not great.
read = cp.read(filename)
if not read:
raise OSError(f'Failed to read {filename}')
for section_name, section in cp.items():
idx = section_name.find(':')
if idx >= 0:
section_name, group = section_name[: idx + 1], section_name[idx + 1 :]
if not section_name or not group:
raise ValueError('Section name components cannot be empty')
if ':' in group:
raise ValueError('Section name cannot contain more than one ":"')
else:
group = None
for key, value in section.items():
if item := CONFIGFILE_ITEMS.get(f'{section_name}/{key}'):
item.apply_config(namespace, section_name, group, key, value)
else:
print(f'Unknown config setting [{section_name}] {key}=', file=sys.stderr)
def config_example() -> Iterator[str]:
prev_section: Optional[str] = None
for item in CONFIG_ITEMS:
section, key, value = item.config_example()
if section:
if prev_section != section:
if prev_section:
yield ''
yield f'[{section}]'
prev_section = section
yield f'{key} = {value}'
class PagerHelpAction(argparse._HelpAction): # pylint: disable=protected-access
def __call__(
self,
parser: argparse.ArgumentParser,
namespace: argparse.Namespace,
values: Union[str, Sequence[Any], None] = None,
option_string: Optional[str] = None,
) -> None:
page(parser.format_help(), True)
parser.exit()
def create_parser() -> argparse.ArgumentParser:
p = argparse.ArgumentParser(
description='Build and sign Unified Kernel Images',
usage='\n '
+ textwrap.dedent('''\
ukify {b}build{e} [--linux=LINUX] [--initrd=INITRD] [options…]
ukify {b}genkey{e} [options…]
ukify {b}inspect{e} FILE… [options…]
''').format(b=Style.bold, e=Style.reset),
allow_abbrev=False,
add_help=False,
epilog='\n '.join(('config file:', *config_example())),
formatter_class=argparse.RawDescriptionHelpFormatter,
)
for item in CONFIG_ITEMS:
item.add_to(p)
# Suppress printing of usage synopsis on errors
p.error = lambda message: p.exit(2, f'{p.prog}: error: {message}\n') # type: ignore
# Make --help paged
p.add_argument(
'-h', '--help',
action=PagerHelpAction,
help='show this help message and exit',
) # fmt: skip
return p
def resolve_at_path(value: Optional[str]) -> Union[Path, str, None]:
if value and value.startswith('@'):
return Path(value[1:])
return value
def finalize_options(opts: argparse.Namespace) -> None:
# Figure out which syntax is being used, one of:
# ukify verb --arg --arg --arg
# ukify linux initrd…
if len(opts.positional) >= 1 and opts.positional[0] == 'inspect':
opts.verb = opts.positional[0]
opts.files = opts.positional[1:]
if not opts.files:
raise ValueError('file(s) to inspect must be specified')
if len(opts.files) > 1 and opts.json != 'off':
# We could allow this in the future, but we need to figure out the right structure
raise ValueError('JSON output is not allowed with multiple files')
elif len(opts.positional) == 1 and opts.positional[0] in VERBS:
opts.verb = opts.positional[0]
elif opts.linux or opts.initrd:
raise ValueError('--linux=/--initrd= options cannot be used with positional arguments')
else:
print("Assuming obsolete command line syntax with no verb. Please use 'build'.", file=sys.stderr)
if opts.positional:
opts.linux = Path(opts.positional[0])
# If we have initrds from parsing config files, append our positional args at the end
opts.initrd = (opts.initrd or []) + [Path(arg) for arg in opts.positional[1:]]
opts.verb = 'build'
# Check that --pcr-public-key=, --pcr-private-key=, and --phases=
# have either the same number of arguments or are not specified at all.
# Also check that --pcr-public-key= and --pcr-certificate= are not set at the same time.
# But allow a single public key, for offline PCR signing, to pre-populate the JSON object
# with the certificate's fingerprint.
n_pcr_cert = None if opts.pcr_certificates is None else len(opts.pcr_certificates)
n_pcr_pub = None if opts.pcr_public_keys is None else len(opts.pcr_public_keys)
n_pcr_priv = None if opts.pcr_private_keys is None else len(opts.pcr_private_keys)
n_phase_path_groups = None if opts.phase_path_groups is None else len(opts.phase_path_groups)
n_policyrefs = None if opts.policyrefs is None else len(opts.policyrefs)
if opts.policy_digest and n_pcr_priv is not None:
raise ValueError('--pcr-private-key= cannot be specified with --policy-digest')
if (
opts.policy_digest
and (n_pcr_pub is None or n_pcr_pub != 1)
and (n_pcr_cert is None or n_pcr_cert != 1)
):
raise ValueError('--policy-digest requires exactly one --pcr-public-key= or --pcr-certificate=')
if n_pcr_pub is not None and n_pcr_priv is not None and n_pcr_pub != n_pcr_priv:
raise ValueError('--pcr-public-key= specifications must match --pcr-private-key=')
if n_pcr_cert is not None and n_pcr_priv is not None and n_pcr_cert != n_pcr_priv:
raise ValueError('--pcr-certificate= specifications must match --pcr-private-key=')
if n_pcr_pub is not None and n_pcr_cert is not None:
raise ValueError('--pcr-public-key= and --pcr-certificate= cannot be used at the same time')
if n_phase_path_groups is not None and n_phase_path_groups != n_pcr_priv:
raise ValueError('--phases= specifications must match --pcr-private-key=')
if n_policyrefs is not None and n_policyrefs != n_pcr_priv:
raise ValueError('--policyref= specifications must match --pcr-private-key=')
if opts.sign_initrd_pcrs and not (n_pcr_priv or opts.policy_digest):
raise ValueError('--sign-initrd-pcrs requires --pcr-private-key= or --policy-digest')
opts.cmdline = resolve_at_path(opts.cmdline)
if isinstance(opts.cmdline, str):
# Drop whitespace from the command line. If we're reading from a file,
# we copy the contents verbatim. But configuration specified on the command line
# or in the config file may contain additional whitespace that has no meaning.
opts.cmdline = ' '.join(opts.cmdline.split())
opts.os_release = resolve_at_path(opts.os_release)
if opts.os_release == '':
# If --os-release= with an empty string was passed, treat that as
# explicitly disabling the .osrel section, and do not fallback to the
# system's os-release files.
pass
elif opts.os_release is None and opts.linux:
p = Path('/etc/os-release')
if not p.exists():
p = Path('/usr/lib/os-release')
opts.os_release = p
if opts.efi_arch is None:
opts.efi_arch = guess_efi_arch()
if opts.stub is None and not opts.join_pcrsig:
if opts.linux is not None:
opts.stub = Path(f'/usr/lib/systemd/boot/efi/linux{opts.efi_arch}.efi.stub')
else:
opts.stub = Path(f'/usr/lib/systemd/boot/efi/addon{opts.efi_arch}.efi.stub')
if opts.signing_engine and opts.signing_provider:
raise ValueError('Only one of --signing-engine= and --signing-provider= may be specified')
if opts.signing_engine is None and opts.signing_provider is None and opts.sb_key:
opts.sb_key = Path(opts.sb_key)
if opts.certificate_provider is None and opts.sb_cert:
opts.sb_cert = Path(opts.sb_cert)
if bool(opts.sb_key) ^ bool(opts.sb_cert):
# one param only given, sbsign needs both
raise ValueError(
'--secureboot-private-key= and --secureboot-certificate= must be specified together'
)
elif bool(opts.sb_key) and bool(opts.sb_cert):
# both param given, infer sbsign and in case it was given, ensure signtool=sbsign
if opts.signtool and opts.signtool not in ('sbsign', 'systemd-sbsign'):
raise ValueError(
f'Cannot provide --signtool={opts.signtool} with --secureboot-private-key= and --secureboot-certificate='
)
if not opts.signtool:
opts.signtool = 'sbsign'
elif bool(opts.sb_cert_name):
# sb_cert_name given, infer pesign and in case it was given, ensure signtool=pesign
if opts.signtool and opts.signtool != 'pesign':
raise ValueError(
f'Cannot provide --signtool={opts.signtool} with --secureboot-certificate-name='
)
opts.signtool = 'pesign'
if opts.signing_provider and opts.signtool != 'systemd-sbsign':
raise ValueError('--signing-provider= can only be used with --signtool=systemd-sbsign')
if opts.certificate_provider and opts.signtool != 'systemd-sbsign':
raise ValueError('--certificate-provider= can only be used with --signtool=systemd-sbsign')
if opts.sign_kernel and not opts.sb_key and not opts.sb_cert_name:
raise ValueError(
'--sign-kernel requires either --secureboot-private-key= and --secureboot-certificate= (for sbsign) or --secureboot-certificate-name= (for pesign) to be specified'
)
opts.profile = resolve_at_path(opts.profile)
if opts.profile and isinstance(opts.profile, Path):
opts.profile = opts.profile.read_text()
if opts.join_profiles and not opts.profile:
# If any additional profiles are added, we need a base profile as well so add one if
# one wasn't explicitly provided
opts.profile = 'ID=main'
if opts.pcrsig and not opts.join_pcrsig:
raise ValueError('--pcrsig requires --join-pcrsig')
if opts.join_pcrsig and not opts.pcrsig:
raise ValueError('--join-pcrsig requires --pcrsig')
if opts.pcrsig and (
opts.linux
or opts.initrd
or opts.profile
or opts.join_profiles
or opts.microcode
or opts.sbat
or opts.uname
or opts.os_release
or opts.cmdline
or opts.hwids
or opts.splash
or opts.devicetree
or opts.devicetree_auto
or opts.pcr_private_keys
or opts.pcr_public_keys
or opts.pcr_certificates
):
raise ValueError('--pcrsig and --join-pcrsig cannot be used with other sections')
if opts.pcrsig:
opts.pcrsig = resolve_at_path(opts.pcrsig)
if isinstance(opts.pcrsig, Path):
opts.pcrsig = opts.pcrsig.read_text()
if opts.verb == 'build' and opts.output is None:
if opts.linux is None:
raise ValueError('--output= must be specified when building a PE addon')
suffix = '.efi' if opts.sb_key or opts.sb_cert_name else '.unsigned.efi'
opts.output = opts.linux.name + suffix
# Now that we know if we're inputting or outputting, really parse section config
f = Section.parse_output if opts.verb == 'inspect' else Section.parse_input
opts.sections = [f(s) for s in opts.sections]
# A convenience dictionary to make it easy to look up sections
opts.sections_by_name = {s.name: s for s in opts.sections}
def parse_args(args: Optional[list[str]] = None) -> argparse.Namespace:
opts = create_parser().parse_args(args)
# argparse puts some unknown options in opts.positional. Make sure we don't
# try to interpret something that is an option as a positional argument.
if any((bad_opt := o).startswith('-') for o in opts.positional):
raise ValueError(f'Unknown option: {bad_opt.partition("=")[0]}')
apply_config(opts)
finalize_options(opts)
return opts
def main() -> None:
opts = UkifyConfig.from_namespace(parse_args())
if opts.summary:
# TODO: replace pprint() with some fancy formatting.
pprint.pprint(vars(opts))
elif opts.verb == 'build':
check_inputs(opts)
make_uki(opts)
elif opts.verb == 'genkey':
check_cert_and_keys_nonexistent(opts)
generate_keys(opts)
elif opts.verb == 'inspect':
inspect_sections(opts)
else:
assert False
if __name__ == '__main__':
main()