Firmware policy

firmware_policy ¶

A Firmware policy management tools.

Summary: A firmware policy is conceptually a set of key value pair "rules". Rules can be 1-time actions, states persistent while the policy is in effect, or targeting information describing the machine where the policy is applicable

Each key is composed of a UINT32 RootKey followed by String SubKeyName & ValueName For example: RootKey = 0xEF100000 SubKeyName = "PolicyGroupFoo" ValueName = "TpmClear" MyExampleKey = EF100000_PolicyGroupFoo_TpmClear

Each value has a type that can be primitive or a variable-length structure.

¶

The firmware policy binary, pack(1), little endian, is as follows:

UINT16 FormatVersion UINT32 PolicyVersion GUID PolicyPublisher UINT16 Reserved1Count # 0 Reserved1[Reserved1Count] # not present, not supported by this library UINT32 OptionFlags # 0 UINT16 Reserved2Count # 0 UINT16 RulesCount Reserved2[Reserved2Count] # not present for FW policies, partial support by this library RULE Rules[RulesCount] # inline, not a pointer, see class Rule below BYTE ValueTable[] #inline, not a pointer

¶

A RULE structure is as follows

UINT32 RootKey UINT32 OffsetToSubKeyName # ValueTable offset UINT32 OffsetToValueName # ValueTable offset UINT32 OffsetToValue # ValueTable offset to a PolicyValueType + PolicyValue

¶

Each Rule corresponds to 3 entries in the ValueTable Rules may, however, re-use identical ValueTable entries to save space For example, multiple Rules with the same SubKeyName may report the same SubKeyNameOffset

PolicyString SubKeyName # may or may not be NULL terminated, usually not PolicyString Valuename # may or may not be NULL terminated, usually not PolicyValue # Begins with a UINT16 PolicyValueType, followed by the actual value, may be NULL terminated

¶

Conventions

_init__ constructors are to be used when creating new objects from desired values.
When the number of parameters is small, __init__ may also take a stream parameter
which will be deserialized to initialize the object in lieu of the other parameters.
When the number of parameters is large, initialization from stream is factored out
into a separate class method FromFileStream().  This overhead did not seem merited
when the number of overall parameters was small.

¶

Rule ¶

Class for managing Rule structures.

Class for storing, serializing, deserializing, & printing RULE elements

init ¶

__init__(
    RootKey: int,
    SubKeyName: str,
    ValueName: str,
    Value: PolicyValue,
    OffsetToSubKeyName: int = 0,
    OffsetToValueName: int = 0,
    OffsetToValue: int = 0,
) -> Rule

Inits the Rule Object.

Parameters:

Name	Type	Description	Default
`RootKey`	`int`	The root key value	required
`SubKeyName`	`str`	the subkey name	required
`ValueName`	`str`	Name of the rule value	required
`Value`	`PolicyValue`	The value.	required
`OffsetToSubKeyName`			`0`
`OffsetToValueName`			`0`
`OffsetToValue`			`0`

eq ¶

__eq__(other: Rule) -> bool

Rule table offsets are not considered for equivalency, only the actual key/value.

FromFsAndVtOffset `classmethod` ¶

FromFsAndVtOffset(fs: BinaryIO, vtOffset: int) -> Rule

Construct a Rule initialized from a deserialized stream and vtOffset.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	File stream to read from	required
`vtOffset`	`int`	offset in fs to get the ValueTable	required

Raises:

Type	Description
`Exception`	Invalid File Stream or value table offset

FromFsAndVtBytes `classmethod` ¶

FromFsAndVtBytes(fs: BinaryIO, vt: bytes) -> Rule

Contstruct a Rule initialized from a deserialized stream and value table.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	File stream to read from	required
`vt`	`bytes`	bytes representing a value table	required

Raises:

Type	Description
`Exception`	Invalid File Stream or value table

Print ¶

Print(prefix: str = '') -> None

Prints the contents of the Rule.

Parameters:

Name	Type	Description	Default
`prefix`			`''`

Serialize ¶

Serialize(
    ruleOut: bytearray, valueOut: bytearray, offsetInVT: int
) -> None

Serialize Rule.

Parameters:

Name	Type	Description	Default
`ruleOut`	`bytearray`	serialized Reserved2 rule	required
`valueOut`	`bytearray`	not currently used	required
`offsetInVT`	`int`	not currently used	required

PolicyValueType ¶

Class for managing PolicyValueTypes.

Class for storing, serializing, deserializing, & printing PolicyValue Types

init ¶

__init__(Type: int) -> PolicyValueType

Inits the PolicyValueType.

Parameters:

Name	Type	Description	Default
`Type`	`obj`	POLICY_VALUE_TYPE_*	required

Raises:

Type	Description
`Exception`	Unsupported ValueType

FromFileStream `classmethod` ¶

FromFileStream(
    fs: BinaryIO, fsOffset: int = None
) -> PolicyValueType

Load a Policy Value Type from a file stream.

NOTE: if fsOffset is not specified, stream fs position is at beginning of struct.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream to read	required
`fsOffset`			`None`

FromBytes `classmethod` ¶

FromBytes(b: bytes, bOffset: int = 0) -> PolicyValueType

Inits a PolicyStringValue from a filestream.

Parameters:

Name	Type	Description	Default
`b`	`bytes`	bytes to read	required
`bOffset`			`0`

Print ¶

Print(prefix: str = '') -> None

Prints the contents of the Policy String Type.

Parameters:

Name	Type	Description	Default
`prefix`			`''`

Serialize ¶

Serialize(valueOut: bytearray) -> None

Serialize the Policy String Type.

Parameters:

Name	Type	Description	Default
`valueOut`	`bytearray`	serialized object	required

Get ¶

Get() -> int

Returns the value type.

PolicyString ¶

Class for managing PolicyString structures.

Class for storing, serializing, deserializing, & printing PolicyString Types NOTE: This type is used both in the keys as SubKeyName and ValueName and it can be a value. When used as a value, a NULL may follow the string, but the NULL will not be included in the string size

16-bit, little endian, size of the string in bytes followed by a UTF-16LE string, no NULL terminator

Example of "PlatformID" \x14\x00P\x00l\x00a\x00t\x00f\x00o\x00r\x00m\x00I\x00D\x00

The trailing \x00 is not a NULL, it is UTF-16LE encoding of "D"

init ¶

__init__(String: str = None) -> PolicyString

Inits PolicyStructure.

Parameters:

Name	Type	Description	Default
`String`			`None`

FromFileStream `classmethod` ¶

FromFileStream(
    fs: BinaryIO, fsOffset: int = None
) -> PolicyString

Inits a PolicyString from a file stream.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	File stream to read	required
`fsOffset`			`None`

Raises:

Type	Description
`Exception`	string length mismatch

FromBytes `classmethod` ¶

FromBytes(b: bytes, bOffset: int = 0) -> PolicyString

Inits a PolicyString from a filestream.

Parameters:

Name	Type	Description	Default
`b`	`bytes`	bytes to read	required
`bOffset`			`0`

Raises:

Type	Description
`Exception`	string length mismatch

Print ¶

Print(prefix: str = '') -> None

Prints the contents of the Policy String.

Parameters:

Name	Type	Description	Default
`prefix`			`''`

Serialize ¶

Serialize(valueOut: bytearray) -> None

Serialize the Policy String.

Parameters:

Name	Type	Description	Default
`valueOut`	`bytearray`	serialized object	required

PolicyValue ¶

Class for managing PolicyValue structures.

Class for storing, serializing, deserializing, & printing policy values Typically handles primitive types itself, or delegates to other classes for non-primitive structures, e.g. PolicyString

Attributes:

Name	Type	Description
`valueType`	`PolicyValueType`	Policy Value Type
`value`	`struct`	Policy String, dword, qword

init ¶

__init__(
    valueType: PolicyValueType, value: str
) -> PolicyValue

Inits a Policy Value.

Parameters:

Name	Type	Description	Default
`valueType`	`PolicyValueType`	Policy Value Type	required
`value`	`struct`	Policy value string, dword, or qword	required

FromFileStream `classmethod` ¶

FromFileStream(
    fs: BinaryIO, fsOffset: int = None
) -> PolicyValue

Load a Policy Value from a file stream.

NOTE: if fsOffset is not specified, stream fs position is at beginning of struct.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream to read	required
`fsOffset`			`None`

Raises:

Type	Description
`Exception`	if STRICT is True, unsupported PolicyValueType

FromBytes `classmethod` ¶

FromBytes(b: bytes, bOffset: int = 0) -> PolicyValue

Load a Policy Value from bytes.

Parameters:

Name	Type	Description	Default
`b`	`bytes`	bytes to parse	required
`bOffset`			`0`

GetValueType ¶

GetValueType() -> str

Returns the value type.

Print ¶

Print(prefix: str = '') -> None

Prints the contents of the object.

Parameters:

Name	Type	Description	Default
`prefix`			`''`

Serialize ¶

Serialize(valueOut: bytearray) -> None

Serializes the object to valueOut.

Parameters:

Name	Type	Description	Default
`valueOut`	`bytearray`	object to write bytes to.	required

Raises:

Type	Description
`Exception`	Value Type not supported.

Reserved2 ¶

Class for managing Reserved2 structures.

For testing non-firmware, legacy policies Implementation can do basic parsing of rules but not values For test purposes only

init ¶

__init__(
    fs: BinaryIO = None, vtOffset: int = 0
) -> Reserved2

Initializes the Reserved2 structure.

Parameters:

Name	Type	Description	Default
`fs`			`None`
`vtOffset`			`0`

PopulateFromFileStream ¶

PopulateFromFileStream(
    fs: BinaryIO, vtOffset: int = 0
) -> None

Initializes the Reserved2 structure from a filestream.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	file stream to read from	required
`vtOffset`	`int`	not currently used	`0`

Raises:

Type	Description
`Exception`	Invalid File stream
`Exception`	if STRICT is True, cannot deserialize reserved2 values

Print ¶

Print(prefix: str = '') -> None

Prints the Reserved2 structure.

Parameters:

Name	Type	Description	Default
`prefix`	`str`	prefix to append when printing to terminal	`''`

Serialize ¶

Serialize(
    ruleOut: bytearray,
    valueOut: bytearray = None,
    offsetInVT: int = 0,
) -> None

Serialize Reserved2 rule.

Parameters:

Name	Type	Description	Default
`ruleOut`	`bytearray`	serialized Reserved2 rule	required
`valueOut`	`bytearray`	not currently used	`None`
`offsetInVT`	`int`	not currently used	`0`

Raises:

Type	Description
`Exception`	if STRICT is True, value serialization not supported

FirmwarePolicy ¶

Class for managing Firmware Policy structures.

Manages storing, serializing, deserializing, & printing Firmware Policy structures

Typically handles primitive types itself, or delegates to other classes for non-primitive structures, e.g. Rule, PolicyValue, PolicyString

FW_POLICY_VALUE_STATES_MASK `class-attribute` `instance-attribute` ¶

FW_POLICY_VALUE_STATES_MASK = 18446462603027742720

Defined Policy Actions

FW_POLICY_VALUE_ACTION_STRINGS `class-attribute` `instance-attribute` ¶

FW_POLICY_VALUE_ACTION_STRINGS = {
    FW_POLICY_VALUE_ACTION_SECUREBOOT_CLEAR: "Clear UEFI Secure Boot Keys",
    FW_POLICY_VALUE_ACTION_TPM_CLEAR: "Clear the Trusted Platform Module (TPM)",
}

Defined Policy States

init ¶

__init__(fs: BinaryIO = None) -> FirmwarePolicy

Initializes a Firmware Policy object.

Parameters:

Name	Type	Description	Default
`fs`			`None`

AddRule ¶

AddRule(regRule: Rule) -> bool

Adds a rule to the Firmware Policy object representation.

WARNING: Does not update the valuetable, use Serialize to do that after all rules are added.

Parameters:

Name	Type	Description	Default
`regRule`	`Rule`	rule to add	required

Returns:

Type	Description
`bool`	True if added, False if it already existed.

SetDevicePolicy ¶

SetDevicePolicy(policy: int) -> None

Adds a Rule for the 64-bit policy value bitfield.

NOTE: The "key" is a well-known constant assigned in the body of this method

Parameters:

Name	Type	Description	Default
`policy`	`int`	the 64-bit bitfield value for associated key.	required

SetDeviceTarget ¶

SetDeviceTarget(target: dict) -> None

Sets the device target dictionary.

Parameters:

Name	Type	Description	Default
`target`	`dict`	ValueName/Value pairs	required

SerializeToStream ¶

SerializeToStream(stream: BinaryIO) -> None

Serializes the Firmware Policy to a stream.

Parameters:

Name	Type	Description	Default
`stream`	`BinaryIO`	stream to write to	required

Serialize ¶

Serialize(output: bytearray) -> None

Serializes the Firmware Policy to a bytearray.

Parameters:

Name	Type	Description	Default
`output`	`bytearray`	bytearray to write to.	required

FromFileStream ¶

FromFileStream(
    fs: BinaryIO, parseByBytes: bool = True
) -> None

Initializes the Firmware Policy from a FileStream.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	Filestream to read from	required
`parseByBytes`			`True`

Raises:

Type	Description
`Exception`	an invalid file stream was provided.

PrintDevicePolicy ¶

PrintDevicePolicy(
    devicePolicy: int, prefix: str = ""
) -> None

Prints the device policy.

Print ¶

Print() -> None

Prints the firmware policy structure.

Firmware policy

firmware_policy ¶

Rule ¶

__init__ ¶

__eq__ ¶

FromFsAndVtOffset classmethod ¶

FromFsAndVtBytes classmethod ¶

Print ¶

Serialize ¶

PolicyValueType ¶

__init__ ¶

FromFileStream classmethod ¶

FromBytes classmethod ¶

Print ¶

Serialize ¶

Get ¶

PolicyString ¶

__init__ ¶

FromFileStream classmethod ¶

FromBytes classmethod ¶

Print ¶

Serialize ¶

PolicyValue ¶

__init__ ¶

FromFileStream classmethod ¶

FromBytes classmethod ¶

GetValueType ¶

Print ¶

Serialize ¶

Reserved2 ¶

__init__ ¶

PopulateFromFileStream ¶

Print ¶

Serialize ¶

FirmwarePolicy ¶

FW_POLICY_VALUE_STATES_MASK class-attribute instance-attribute ¶

FW_POLICY_VALUE_ACTION_STRINGS class-attribute instance-attribute ¶

__init__ ¶

AddRule ¶

SetDevicePolicy ¶

SetDeviceTarget ¶

SerializeToStream ¶

Serialize ¶

FromFileStream ¶

PrintDevicePolicy ¶

Print ¶

init ¶

eq ¶

FromFsAndVtOffset `classmethod` ¶

FromFsAndVtBytes `classmethod` ¶

init ¶

FromFileStream `classmethod` ¶

FromBytes `classmethod` ¶

init ¶

FromFileStream `classmethod` ¶

FromBytes `classmethod` ¶

init ¶

FromFileStream `classmethod` ¶

FromBytes `classmethod` ¶

init ¶

FW_POLICY_VALUE_STATES_MASK `class-attribute` `instance-attribute` ¶

FW_POLICY_VALUE_ACTION_STRINGS `class-attribute` `instance-attribute` ¶

init ¶