BIOS Operations

BIOS/UEFI configuration and management commands.

Expecting a failure

Several of these commands take a should_fail flag. It asserts that the target refused the operation, which is how you test that firmware rejects a signature it should not accept.

Only the target can satisfy it. If the step never reaches the target the step fails, whatever should_fail says:

a key_path or cert_path that does not exist, or holds something that is not a valid key or certificate
a parameter the command needs but the description does not set
an SSH connection that could not be opened, or that dropped
the step timeout expiring

The log says which of the two happened:

✓ the target refused to update the enrolled certificate, as expected. The certificate configuration is unchanged.

✗ bios certificate 'update' never reached the target: failed to load certificate: x509: malformed certificate
  should_fail expects the target to refuse the operation, and it was never asked

A step that expects a rejection and gets one for the wrong reason proves nothing, so the second case is reported as a failure rather than counted as the refusal.

BIOS Certificate

Check BIOS Options on the DUT.

Attribute	Type	Required	Default	Description
`cmd`	`const`	Yes	`bios certificate management`	Command Name
`name`	`string`	Yes		Name to uniquely identify the teststep. This name will show up in reports, logs and the WebUI
`transport`	`TransportObject`	Yes		Additional transport options
`options`	`OptionsObject`	No		Additional command options
`parameters`	`BIOS Certificate Options`	Yes		Options passed into BIOS Certificate

BIOS Certificate Options

Attribute	Type	Required	Description
`password`	`string`	Either of*	BIOS Password
`old_password`	`string`	Either of*	Old BIOS Password
`cert_path`	`string`	Either of*	BIOS Certificate
`key_path`	`string`	Either of*	BIOS Certificate Private Key
`serial`	`string`	Either of*	Serial number of device
`expect`	`BIOS Certificate Expect Options`	No	Array of expected BIOS Certificate Options

BIOS Certificate Expect Options

Attribute	Type	Required	Default	Description
`should_fail`	`bool`	No	`false`	Expect the firmware to refuse the operation. See Expecting a failure.

BIOS Certificate Example

- cmd: bios certificate management
  name: Enable certificate
  transport: *transport
  parameters:
    command: enable
    password: mypassword
    cert_path: /root/default-tools/system-suite/4k/new/cert.pem
- cmd: bios certificate management
  name: Check certificate thumbprint
  transport: *transport
  parameters:
    command: check
    cert_path: /root/default-tools/system-suite/4k/new/cert.pem
- cmd: bios certificate management
  name: Disable certificate
  transport: *transport
  parameters:
    command: disable
    key_path: /root/default-tools/system-suite/4k/new/key.pem
    password: mypassword
- cmd: bios certificate management
  name: Clear certificate
  transport: *transport
  parameters:
    command: clear
    key_path: /root/default-tools/system-suite/4k/new/key.pem
- cmd: bios certificate management
  name: Update password
  transport: *transport
  parameters:
    command: set-password
    old_password: mypassword
    password: mynewpassword

BIOS Settings Get

Check BIOS Options on the DUT.

Attribute	Type	Required	Default	Description
`cmd`	`const`	Yes	`get bios setting`	Command Name
`name`	`string`	Yes		Name to uniquely identify the teststep. This name will show up in reports, logs and the WebUI
`transport`	`TransportObject`	Yes		Additional transport options
`options`	`OptionsObject`	No		Additional command options
`parameters`	`BIOS Settings Get Options`	Yes		Options passed into BIOS Settings Get

BIOS Settings Get Options

Attribute	Type	Required	Default	Description
`expect`	`[]BIOS Settings Get Expect Options`	Yes		Array of expected BIOS Settings

BIOS Settings Get Expect Options

Attribute	Type	Required	Default	Description
`option`	`string`	Yes		BIOS Option
`value`	`string`	Yes		Expected Value (supports regex)

BIOS Settings Get Example

cmd: get bios setting
name: "Check BIOS Settings"
transport: *transport
parameters:
  expect:
    - option: BootDisplayDevice
      value: LCD
    - option: BootMode
      value: Quick
    - option: BootOrderLock
      value: Disable

BIOS Settings Set

Try to set BIOS Options on the DUT.

Attribute	Type	Required	Default	Description
`cmd`	`const`	Yes	`set bios setting`	Command Name
`name`	`string`	Yes		Name to uniquely identify the teststep. This name will show up in reports, logs and the WebUI
`transport`	`TransportObject`	Yes		Additional transport options
`options`	`OptionsObject`	No		Additional command options
`parameters`	`BIOS Settings Set Options`	Yes		Options passed into BIOS Settings Set

BIOS Settings Set Options

Attribute	Type	Required	Description
`password`	`string`	No	BIOS Password
`key_path`	`string`	No	BIOS Cert Key
`bios_options`	`[]BIOS Options`	Yes	Array of BIOS Options to set

BIOS Options

Attribute	Type	Required	Default	Description
`option`	`string`	Yes		BIOS Option
`value`	`string`	Yes		Value to set
`should_fail`	`bool`	No	`false`	Expect the firmware to refuse this write. See Expecting a failure.

BIOS Settings Set Example

cmd: set bios setting
name: "Set Target BIOS Settings"
transport: *transport
parameters:
  password: <bios-password>
  bios_options:
    - option: AlwaysOnUSB
      value: Disable
    - option: FingerprintPasswordAuthentication
      value: Disable

SecureBoot Management

Run different commands, based on sbctl on the DUT.

Attribute	Type	Required	Default	Description
`cmd`	`const`	Yes	`Secure Boot Management`	Command Name
`name`	`string`	Yes		Name to uniquely identify the teststep. This name will show up in reports, logs and the WebUI
`transport`	`TransportObject`	Yes		Additional transport options
`options`	`OptionsObject`	No		Additional command options
`parameters`	`SecureBoot Options`	Yes		Options passed into the `Secure Boot Management` cmd

SecureBoot Options

Attribute	Type	Required	Default	Description
`command`	`string`	Yes		Command to execute. Can be one of: `status`, `enroll-key`, `rotate-key`, `reset`, `custom-key`.
`hierarchy`	`string`	Yes		Hierarchy to use for the key. Can be one of: `db`, `dbx`, `KEK`, `PK`.
`key_file`	`string`	No		Path to the key file used for `enroll-key` and `rotate-key` commands.
`custom_key_file`	`string`	No		Path to the custom key file used for `custom-key` command.
`cert_file`	`string`	No		Path to the certificate file used for `enroll-key` and `rotate-key` commands.
`signing_key_file`	`string`	No		Path to the signing key file used for `enroll-key` and `rotate-key` commands.
`signing_cert_file`	`string`	No		Path to the signing certificate file used for `enroll-key` and `rotate-key` commands.
`append`	`boolean`	No	`false`	Append the key to the existing key database.
`expect`	`SecureBoot Expect Options`	No	`parameters`	Expectations for the command execution.

SecureBoot Expect Options

Attribute	Type	Required	Default	Description
`should_fail`	`boolean`	No	`false`	Expect the target to refuse the operation. See Expecting a failure.
`secure_boot`	`boolean`	Yes	`false`	If set to true, the test step will fail if Secure Boot is not enabled.
`setup_mode`	`boolean`	Yes	`false`	If set to true, the test step will fail if Secure Boot is not in setup mode.

SecureBoot Management Examples

- cmd: Secure Boot Management
  name: Check if SetupMode is enabled
  transport: *transport
  parameters:
    command: status
    expect:
      secure_boot: false
      setup_mode: true

- cmd: Secure Boot Management
  name: Enroll invalid signed PK key
  transport: *transport
  parameters:
    command: custom-key
    hierarchy: PK
    custom_key_file: /tmp/sbctl/keys/invalidPK.auth
    expect:
      should_fail: true

- cmd: Secure Boot Management
  name: Enroll db key
  transport: *transport
  parameters:
    command: enroll-key
    hierarchy: db
    key_file: /tmp/sbctl/keys/DB.key
    cert_file: /tmp/sbctl/keys/DB.crt
    signing_key_file: /tmp/sbctl/keys/KEK.key
    signing_cert_file: /tmp/sbctl/keys/KEK.crt
    append: true

- cmd: Secure Boot Management
  name: Rotate db key
  transport: *transport
  parameters:
    command: rotate-key
    hierarchy: db
    key_file: /tmp/sbctl/keys-new/DB.key
    cert_file: /tmp/sbctl/keys-new/DB.crt
    signing_key_file: /tmp/sbctl/keys/KEK.key
    signing_cert_file: /tmp/sbctl/keys/KEK.crt

- cmd: Secure Boot Management
  name: Reset db key
  transport: *transport
  parameters:
    command: reset
    hierarchy: db
    signing_key_file: /tmp/sbctl/keys/KEK.key
    signing_cert_file: /tmp/sbctl/keys/KEK.crt
    cert_file: /tmp/sbctl/keys/DB.crt