Authenticated variables structure support

authenticated_variables_structure_support ¶

Module containing Authenticated Variable Structure definitions based on UEFI specification (2.7).

Each object can be created and or populated from a file stream. Each object can be written to a filesteam as binary and printed to the console in text.

CommonUefiStructure ¶

This structure contains the methods common across all UEFI Structures.

init ¶

__init__() -> CommonUefiStructure

Inits the object.

write `abstractmethod` ¶

write(fs: BinaryIO) -> None

Writes the object to a filestream.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	a filestream object to write the object to	required

decode `abstractmethod` ¶

decode(fs: BinaryIO, decodesize: int) -> None

Populates the object from a filestream.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO \| Bytes`	a filestream object to read from	required
`decodesize`	`int`	number of bytes to decode as the object	required

encode `abstractmethod` ¶

encode() -> bytes

Returns the object as a binary object.

Returns:

Name	Type	Description
`bytes`	`bytes`	a binary object of the object

print `abstractmethod` ¶

print(outfs: IO = sys.stdout) -> None

Prints the object to the console.

EfiSignatureDataEfiCertX509 ¶

An object representing a EFI_SIGNATURE_DATA Structure for X509 Certs.

SignatureOwner `property` `writable` ¶

SignatureOwner: UUID

Returns the Signature Owner as a uuid object.

SignatureData `property` `writable` ¶

SignatureData: bytes

Returns the Signature Data.

init ¶

__init__(
    decodefs: BinaryIO = None,
    decodesize: int = 0,
    createfs: BinaryIO = None,
    cert: bytes = None,
    sigowner: uuid.UUID = None,
) -> EfiSignatureDataEfiCertX509

Inits the object.

Parameters:

Name	Type	Description	Default
`decodefs`	`BinaryIO`	a filestream object of binary content that is the structure encoded	`None`
`decodesize`	`int`	number of bytes to decode as the EFI_SIGNATURE_DATA object (guid + x509 data)	`0`
`createfs`	`BinaryIO`	a filestream object that is the DER encoded x509 cert	`None`
`cert`	`bytes`	the x509 certificate to initialize this object	`None`
`sigowner`	`UUID`	the uuid object of the signature owner guid	`None`

Raises:

Type	Description
`ValueError`	Invalid FileStream size
`ValueError`	Invalid Parameters

lt ¶

__lt__(other: EfiSignatureDataEfiCertX509) -> bool

Less-than comparison for sorting. Looks at signature_data only, not signature_owner.

PopulateFromFileStream ¶

PopulateFromFileStream(
    fs: BinaryIO, decodesize: int
) -> None

Decodes an object from a filestream.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream	required
`decodesize`	`int`	amount to decode.	required

Raises:

Type	Description
`ValueError`	Invalid filestream
`ValueError`	Invalid Decode Size

decode ¶

decode(fs: BinaryIO, decodesize: int) -> None

Decodes an object from a filestream.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream	required
`decodesize`	`int`	amount to decode.	required

Raises:

Type	Description
`ValueError`	Invalid filestream
`ValueError`	Invalid Decode Size

Print ¶

Print(
    compact: bool = False, outfs: IO = sys.stdout
) -> None

Prints to the console.

print ¶

print(
    compact: bool = False, outfs: IO = sys.stdout
) -> None

Prints to the console.

Write ¶

Write(fs: BinaryIO) -> None

Write the object to the filestream.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream	required

Raises:

Type	Description
`ValueError`	Invalid filestream
`ValueError`	Invalid object

write ¶

write(fs: BinaryIO) -> None

Write the object to the filestream.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream	required

Raises:

Type	Description
`ValueError`	Invalid filestream
`ValueError`	Invalid object

GetBytes ¶

GetBytes() -> bytes

Return bytes array produced by Write().

encode ¶

encode() -> bytes

Return bytes array produced by Write().

GetTotalSize ¶

GetTotalSize() -> int

Returns the total size of the object.

get_total_size ¶

get_total_size() -> int

Returns the total size of the object.

EfiSignatureDataEfiCertSha256 ¶

An object representing a EFI_SIGNATURE_DATA Structure for Sha256 Certs.

SignatureOwner `property` `writable` ¶

SignatureOwner: UUID

Returns the Signature Owner as a uuid object.

SignatureData `property` `writable` ¶

SignatureData: bytes

Returns the Signature Data.

init ¶

__init__(
    decodefs: BinaryIO = None,
    createfs: BinaryIO = None,
    digest: bytes = None,
    sigowner: uuid = None,
) -> EfiSignatureDataEfiCertSha256

Inits the object.

Parameters:

Name	Type	Description	Default
`decodefs`	`BinaryIO`	a filestream object of binary content that is the structure encoded	`None`
`createfs`	`BinaryIO`	a filestream object that is the DER encoded x509 cert	`None`
`digest`	`bytes`	a bytes object that contains the hash value for new signature data	`None`
`sigowner`	`UUID`	the uuid object of the signature owner guid	`None`

Raises:

Type	Description
`Exception`	Invalid FileStream size
`ValueError`	Invalid Parameters

decode ¶

decode(fs: BinaryIO, decodesize: int = -1) -> None

Decodes an object from a filestream.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream	required
`decodesize`	`int`	size of the object to decode (UNUSED)	`-1`

Raises:

Type	Description
`Exception`	Invalid filestream

PopulateFromFileStream ¶

PopulateFromFileStream(fs: BinaryIO) -> None

Loads an object from a filestream.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream	required

Raises:

Type	Description
`Exception`	Invalid filestream

print ¶

print(
    compact: bool = False, outfs: IO = sys.stdout
) -> None

Prints to the console.

Print ¶

Print(
    compact: bool = False, outfs: IO = sys.stdout
) -> None

Prints to the console.

write ¶

write(fs: BinaryIO) -> None

Write the object to the filestream.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream	required

Raises:

Type	Description
`Exception`	Invalid filestream
`Exception`	Invalid object

Write ¶

Write(fs: BinaryIO) -> None

Write the object to the filestream.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream	required

Raises:

Type	Description
`Exception`	Invalid filestream
`Exception`	Invalid object

encode ¶

encode() -> bytes

Return bytes array produced by Write().

GetBytes ¶

GetBytes() -> bytes

Return bytes array produced by Write().

get_total_size ¶

get_total_size() -> int

Returns the total size of the object.

GetTotalSize ¶

GetTotalSize() -> int

Returns the total size of the object.

EfiSignatureDataFactory ¶

Factory class for generating an EFI Signature struct.

factory `staticmethod` ¶

factory(
    fs: BinaryIO, type: uuid.UUID, size: int
) -> Union[
    EfiSignatureDataEfiCertSha256,
    EfiSignatureDataEfiCertX509,
]

This method is a factory for creating the correct Efi Signature Data object from the filestream.

Uses a Filestream of an existing auth payload.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream to read	required
`type`	`UUID`	Guid of the type	required
`size`	`int`	decodesize for x509, struct size for Sha256	required

Factory `staticmethod` ¶

Factory(
    fs: BinaryIO, type: uuid.UUID, size: int
) -> Union[
    EfiSignatureDataEfiCertSha256,
    EfiSignatureDataEfiCertX509,
]

This method is a factory for creating the correct Efi Signature Data object from the filestream.

Uses a Filestream of an existing auth payload.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream to read	required
`type`	`UUID`	Guid of the type	required
`size`	`int`	decodesize for x509, struct size for Sha256	required

Create `staticmethod` ¶

Create(
    type: uuid.UUID,
    ContentFileStream: BinaryIO,
    sigowner: uuid.UUID,
) -> Union[
    EfiSignatureDataEfiCertSha256,
    EfiSignatureDataEfiCertX509,
]

Create a new EFI Sginature Data Object.

Parameters:

Name	Type	Description	Default
`type`	`UUID`	Guid of the type	required
`ContentFileStream`	`BinaryIO`	filestream to read	required
`sigowner`	`UUID`	the uuid object of the signature owner guid	required

create `staticmethod` ¶

create(
    type: uuid.UUID,
    ContentFileStream: BinaryIO,
    sigowner: uuid.UUID,
) -> Union[
    EfiSignatureDataEfiCertSha256,
    EfiSignatureDataEfiCertX509,
]

Create a new EFI Sginature Data Object.

Parameters:

Name	Type	Description	Default
`type`	`UUID`	Guid of the type	required
`ContentFileStream`	`BinaryIO`	filestream to read	required
`sigowner`	`UUID`	the uuid object of the signature owner guid	required

EfiSignatureList ¶

An object representing a EFI_SIGNATURE_LIST.

SignatureData_List `property` `writable` ¶

SignatureData_List: list

Returns the Signature Data List.

init ¶

__init__(
    filestream: BinaryIO = None, typeguid: uuid.UUID = None
) -> EfiSignatureList

Inits the object.

Parameters:

Name	Type	Description	Default
`filestream`			`None`
`typeguid`			`None`

decode ¶

decode(fs: BinaryIO) -> None

Decodes a filestream and generates the structure.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream to load from	required

Raises:

Type	Description
`Exception`	Invalid filestream
`Exception`	Invalid filestream size
`Exception`	Invalid siglist
`Exception`	Invalid parsing

PopulateFromFileStream ¶

PopulateFromFileStream(fs: BinaryIO) -> None

Decodes a filestream and generates the structure.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream to load from	required

Raises:

Type	Description
`Exception`	Invalid filestream
`Exception`	Invalid filestream size
`Exception`	Invalid siglist
`Exception`	Invalid parsing

Print ¶

Print(
    compact: bool = False, outfs: IO = sys.stdout
) -> None

Prints to the console.

print ¶

print(
    compact: bool = False, outfs: IO = sys.stdout
) -> None

Prints to the console.

Write ¶

Write(fs: BinaryIO) -> None

Serializes the object and writes it to a filestream.

Raises:

Type	Description
`Exception`	Invalid filestream
`Exception`	Uninitialized Sig header

write ¶

write(fs: BinaryIO) -> None

Serializes the object and writes it to a filestream.

Raises:

Type	Description
`Exception`	Invalid filestream
`Exception`	Uninitialized Sig header

GetBytes ¶

GetBytes() -> bytes

Return bytes array produced by Write().

encode ¶

encode() -> bytes

Return bytes array produced by Write().

AddSignatureHeader ¶

AddSignatureHeader(
    SigHeader: bytes, SigSize: int = 0
) -> None

Adds the Signature Header.

Raises:

Type	Description
`Exception`	Signature header already set

AddSignatureData ¶

AddSignatureData(
    SigDataObject: Tuple[
        EfiSignatureDataEfiCertX509,
        EfiSignatureDataEfiCertSha256,
    ]
) -> None

Adds the Signature Data.

Raises:

Type	Description
`Exception`	Signature size does not match Sig Data Object size

MergeSignatureList ¶

MergeSignatureList(esl: EfiSignatureList) -> None

Add the EfiSignatureData entries within the supplied EfiSignatureList to the current object.

No sorting or deduplication is performed, the EfiSignatureData elements are simply appended

SortBySignatureDataValue ¶

SortBySignatureDataValue(
    deduplicate: bool = True,
) -> EfiSignatureList

Sort self's signature_data_list by signature_data values (ignores SigOwner) & optionally deduplicate.

When deduplicate is true, remove duplicate signature_data values from self and return them in an EfiSignatureList. This EfiSignatureList of duplicates is itself not deduplicated.

When deduplicate is false, returns an empty EfiSignatureList (has 0 Data elements)

EfiSignatureDatabase ¶

Concatenation of EFI_SIGNATURE_LISTs, as is returned from UEFI GetVariable() on PK, KEK, db, & dbx.

Useful for parsing and building the contents of the Secure Boot variables

EslList `property` `writable` ¶

EslList: List[EfiSignatureList]

Returns the EFI Signature List.

init ¶

__init__(
    filestream: BinaryIO = None,
    esl_list: List[EfiSignatureList] = None,
) -> EfiSignatureDatabase

Inits an Efi Signature Database object.

Parameters:

Name	Type	Description	Default
`filestream`			`None`
`esl_list`			`None`

decode ¶

decode(fs: BinaryIO, decodesize: int = -1) -> None

Decodes a filestream and generates the structure.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream to load from	required
`decodesize`	`int`	Size to decode (UNUSED)	`-1`

Raises:

Type	Description
`Exception`	Invalid filestream
`Exception`	Invalid filestream size

PopulateFromFileStream ¶

PopulateFromFileStream(fs: BinaryIO) -> None

Decodes a filestream and generates the structure.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream to load from	required

Raises:

Type	Description
`Exception`	Invalid filestream
`Exception`	Invalid filestream size

print ¶

print(
    compact: bool = False, outfs: IO = sys.stdout
) -> None

Prints to the console.

Print ¶

Print(
    compact: bool = False, outfs: IO = sys.stdout
) -> None

Prints to the console.

Write ¶

Write(fs: BinaryIO) -> None

Serializes the object and writes it to a filestream.

Raises:

Type	Description
`Exception`	Invalid filestream

write ¶

write(fs: BinaryIO) -> None

Serializes the object and writes it to a filestream.

Raises:

Type	Description
`Exception`	Invalid filestream

GetBytes ¶

GetBytes() -> bytes

Return bytes array produced by Write().

encode ¶

encode() -> bytes

Return bytes array produced by Write().

get_canonical_and_dupes ¶

get_canonical_and_dupes() -> (
    tuple[EfiSignatureDatabase, EfiSignatureDatabase]
)

Compute and return a tuple containing both a canonicalized database & a database of duplicates.

Returns:

Type	Description
`Tuple[EfiSignatureDatabase, EfiSignatureDatabase]`	(canonical, duplicates)

Note

canonical is an EfiSignatureDatabase where EfiSignatureLists are merged (where possible), deduplicated, & sorted, and the EfiSignatureData elements are also deduplicated & sorted duplicates is an EfiSignatureDatabase with EfiSignatureLists containing any duplicated EfiSignatureData entries (only the data contents are checked for effective equality, signature owner is ignored)

GetCanonicalAndDupes ¶

GetCanonicalAndDupes() -> (
    tuple[EfiSignatureDatabase, EfiSignatureDatabase]
)

Compute and return a tuple containing both a canonicalized database & a database of duplicates.

Returns:

Type	Description
`Tuple[EfiSignatureDatabase, EfiSignatureDatabase]`	(canonical, duplicates)

Note

canonical is an EfiSignatureDatabase where EfiSignatureLists are merged (where possible), deduplicated, & sorted, and the EfiSignatureData elements are also deduplicated & sorted duplicates is an EfiSignatureDatabase with EfiSignatureLists containing any duplicated EfiSignatureData entries (only the data contents are checked for effective equality, signature owner is ignored)

get_canonical ¶

get_canonical() -> EfiSignatureDatabase

Return a canonicalized EfiSignatureDatabase, see GetCanonicalAndDupes() for more details.

GetCanonical ¶

GetCanonical() -> EfiSignatureDatabase

Return a canonicalized EfiSignatureDatabase, see GetCanonicalAndDupes() for more details.

get_duplicates ¶

get_duplicates() -> EfiSignatureDatabase

Return an EfiSignatureDatabase of duplicates, see GetCanonicalAndDupes() for more details.

GetDuplicates ¶

GetDuplicates() -> EfiSignatureDatabase

Return an EfiSignatureDatabase of duplicates, see GetCanonicalAndDupes() for more details.

EfiTime ¶

Object representing an EFI_TIME.

init ¶

__init__(
    time: datetime.datetime = datetime.datetime.now(),
    decodefs: BinaryIO = None,
) -> EfiTime

Inits an EFI_TIME object.

Parameters:

Name	Type	Description	Default
`time`	`datetime`	Inits object with specified date (if decodefs not set)	`now()`
`decodefs`	`BinaryIO`	Inits the object with this stream	`None`

decode ¶

decode(fs: BinaryIO) -> datetime.datetime

Decodes a filestream and generates the structure.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream to load from	required

Raises:

Type	Description
`ValueError`	Invalid filestream
`ValueError`	Invalid filestream size

PopulateFromFileStream ¶

PopulateFromFileStream(fs: BinaryIO) -> datetime.datetime

Decodes a filestream and generates the structure.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream to load from	required

Raises:

Type	Description
`Exception`	Invalid filestream
`Exception`	Invalid filestream size

Print ¶

Print(outfs: IO = sys.stdout) -> None

Prints to the console.

print ¶

print(outfs: IO = sys.stdout) -> None

Prints to the console.

Encode ¶

Encode() -> bytes

Return's time as a packed EfiTime Structure.

encode ¶

encode() -> bytes

Get's time as packed EfiTime structure.

write ¶

write(fs: IO) -> None

Serializes the object and writes it to a filestream.

Raises:

Type	Description
`ValueError`	Invalid filestream

Write ¶

Write(fs: IO) -> None

Serializes the object and writes it to a filestream.

Raises:

Type	Description
`ValueError`	Invalid filestream

str ¶

__str__() -> str

String representation of EFI_TIME.

EfiVariableAuthentication2 ¶

An object representing a EFI_VARIABLE_AUTHENTICATION_2.

init ¶

__init__(
    time: datetime.datetime = datetime.datetime.now(),
    decodefs: BinaryIO = None,
) -> EfiVariableAuthentication2

Inits an EFI_VARIABLE_AUTHENTICATION_2 object.

Parameters:

Name	Type	Description	Default
`time`	`datetime`	Inits object with specified date (if decodefs not set)	`now()`
`decodefs`	`BinaryIO`	Inits the object with this stream	`None`

encode ¶

encode() -> bytes

Encodes a new variable into a binary representation.

Returns:

Type	Description
`bytes`	binary representation of the variable

Encode ¶

Encode(outfs: BinaryIO = None) -> bytes

Encodes a new variable into a binary representation.

Parameters:

Name	Type	Description	Default
`outfs`	`BinaryIO`	[default: None] write's to a file stream if provided	`None`

Returns:

Type	Description
`bytes`	binary representation of the variable

decode ¶

decode(fs: BinaryIO) -> None

Decodes a filestream and generates the structure.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream to load from	required

Raises:

Type	Description
`Exception`	Invalid filestream

PopulateFromFileStream ¶

PopulateFromFileStream(fs: BinaryIO) -> None

Decodes a filestream and generates the structure.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream to load from	required

Raises:

Type	Description
`ValueError`	Invalid filestream

print ¶

print(outfs: IO = sys.stdout) -> None

Prints to the console.

Print ¶

Print(outfs: IO = sys.stdout) -> None

Prints to the console.

write ¶

write(fs: BinaryIO) -> None

Serializes the object and writes it to a filestream.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream to write to	required

Raises:

Type	Description
`ValueError`	Invalid filestream

Write ¶

Write(fs: BinaryIO) -> None

Serializes the object and writes it to a filestream.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream to write to	required

Raises:

Type	Description
`ValueError`	Invalid filestream

SetPayload ¶

SetPayload(fs: BinaryIO) -> None

Decodes a filestream and generates the payload.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream to load from	required

Raises:

Type	Description
`ValueError`	Invalid filestream

set_payload ¶

set_payload(fs: BinaryIO) -> None

Decodes a filestream and generates the payload.

Parameters:

Name	Type	Description	Default
`fs`	`BinaryIO`	filestream to load from	required

Raises:

Type	Description
`ValueError`	Invalid filestream

EfiVariableAuthentication2Builder ¶

Builds EfiVariableAuthentication2 variables.

init ¶

__init__(
    name: str,
    guid: str,
    attributes: Union[int, str],
    payload: Optional[Union[io.BytesIO, bytes]] = None,
    efi_time: datetime.datetime = datetime.datetime.now(),
) -> EfiVariableAuthentication2Builder

Builds a EfiVariableAuthentication2 structure.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the UEFI Variable	required
`guid`	`str`	Guid of the namespace the UEFI variable belongs to	required
`attributes`	`int \| str`	Attributes of the UEFI variable	required
`payload`	`BytesIO \| bytes`	binary payload to be signed and used as the value of the variable	`None`
`efi_time`	`datetime`	EFI time of the datetime object	`now()`

get_digest ¶

get_digest() -> bytes

Returns the digest to be signed.

get_signature ¶

get_signature() -> bytes

Returns the Signature of the digest (PKCS#7 ContentInfo or SignedData structure).

update_payload ¶

update_payload(payload: Union[io.BytesIO, bytes]) -> None

Updates the authenticated variables payload and ultimately the digest.

Parameters:

Name	Type	Description	Default
`payload`	`Union[BytesIO, bytes]`	byte array or byte file stream of variable data	required

Returns:

Type	Description
`None`	None

sign ¶

sign(
    signing_certificate: Certificate,
    signing_private_key: RSAPrivateKey,
    additional_certificates: List = [],
    **kwargs: Any
) -> None

Signs an authenticated variable.

Parameters:

Name	Type	Description	Default
`signing_certificate`	`Certificate`	x.509 format public key	required
`signing_private_key`	`RSAPrivateKey`	x.509 format private key	required
`additional_certificates`	`list`	list of x.509 format public keys to include	`[]`
`**kwargs`	`Keyword Arguments`	see Keyword Arguments	`{}`

Other Parameters:

Name	Type	Description
`hash_algorithm`	`hashes`	accepts cryptography.hazmat.primitives.hashes types to specify the hash_algorithm
`omit_content_info`	`bool`	enabled by default, allows to include the content info asn.1 structure

Returns:

Type	Description
`None`	None

finalize ¶

finalize(
    omit_content_info: bool = True,
) -> EfiVariableAuthentication2

Finalizes the signature and returns a EfiVariableAuthentication2.

Parameters:

Name	Type	Description	Default
`omit_content_info`	`bool`	omits the asn.1 content info structure By specification this should be supported (and the SignedData structure) but this has been broken in tianocore for some time now	`True`

Returns:

Type	Description
`EfiVariableAuthentication2`	EfiVariableAuthentication2

EFiVariableAuthentication2 ¶

An object representing a EFI_VARIABLE_AUTHENTICATION_2. DEPRECATED.

init ¶

__init__(
    time: datetime.datetime = datetime.datetime.now(),
    decodefs: BinaryIO = None,
) -> EFiVariableAuthentication2

DEPRECATED. Use EfiVariableAuthentication2() instead. Initializes a EFiVariableAuthentication2.

Authenticated variables structure support