facedancer.request module

Functionality for declaring and working with USB control requests.

class facedancer.request.ControlRequestHandler(handler_function, execution_condition)

Bases: object

Class representing a control request handler.

Instances of this class are generated automatically each time a control request is defined using decorator syntax; and track the association between the relevant handler function and the condition under which it’s executed.

__call__(caller, request)

Primary execution; calls the relevant handler if our conditions are met.

add_condition(condition)

Refines a control request handler such that it’s only called when the added condition is true.

add_field_matcher(field_name, field_value)

Refines a control request handler such that it’s only called when one of its fields matches a given value.

Parameters:

• field_name – The property of the USBControlRequest object to be checked.

• field_value – The value the relevant property must match to be called.

class facedancer.request.USBControlRequest(direction: USBDirection, type: USBRequestType, recipient: USBRequestRecipient, number: int, value: int, index: int, length: int, data: bytes = b'', device: USBDescribable = None)

Bases: object

Class encapsulating a USB control request.

TODO: document parameters

ack(*, blocking: bool = False)

Acknowledge the given request without replying.

Convenience alias for .acknowledge().

Parameters:

blocking – If true, the relevant control request will complete before returning.

acknowledge(*, blocking: bool = False)

Acknowledge the given request without replying.

Parameters:

blocking – If true, the relevant control request will complete before returning.

data: bytes = b''

device: USBDescribable = None

direction: USBDirection

classmethod from_raw_bytes(raw_bytes: bytes, *, device=None)

Creates a request object from a sequence of raw bytes.

Parameters:

• raw_bytes – The raw bytes to create the object from.

• device – The USBDevice to associate with the given request. Optional, but necessary to use the .reply() / .acknowledge() methods.

get_direction() → USBDirection

get_recipient() → USBRequestRecipient

get_type() → USBRequestType

index: int

property index_high: int

property index_low: int

length: int

number: int

raw() → bytes

Returns the raw bytes that compose the request.

recipient: USBRequestRecipient

reply(data: bytes)

Replies to the given request with a given set of bytes.

property request: int

property request_type: int

Fetches the whole request_type byte.

stall()

Stalls the associated device’s control request.

Used to indicate that a given request isn’t supported; or isn’t supported with the provided arguments.

type: USBRequestType

value: int

property value_high: int

property value_low: int

class facedancer.request.USBRequestHandler

Bases: object

Base class for any object that handles USB requests.

handle_request(request: USBControlRequest) → bool

Core control request handler.

This function can be overridden by a subclass if desired; but the typical way to handle a specific control request is to the the @control_request_handler decorators.

Parameters:

request – the USBControlRequest object representing the relevant request

Returns:

true iff the request is handled

facedancer.request.class_request_handler(**kwargs)

Decorator; declares a class request handler. See control_request_handler() for usage.

facedancer.request.control_request_handler(condition=<function <lambda>>, **kwargs)

Decorator that declares a control request handler.

Used while defining a USBDevice, USBInterface, USBEndpoint, or USBOtherRecipient class to declare handlers for that function.

Parameters:

condition – A function that, when evaluated on a USBControlRequest, evaluates true if and only if this function is an appropriate handler.

facedancer.request.get_request_handler_methods(cls) → List[callable]

Returns a list of all handler methods on a given class or object.

This is used to find all methods of an object decorated with the @*_request_handler decorators.

facedancer.request.reserved_request_handler(**kwargs)

Decorator; declares a reserved-type request handler. Not typically used.

facedancer.request.standard_request_handler(**kwargs)

Decorator; declares a standard request handler. See control_request_handler() for usage.

facedancer.request.to_any_endpoint(func)

Decorator; refines a handler so it’s only called on requests with an endpoint recipient.

facedancer.request.to_any_interface(func)

Decorator; refines a handler so it’s only called on requests with an interface recipient.

facedancer.request.to_device(func)

Decorator; refines a handler so it’s only called on requests with a device recipient.

facedancer.request.to_other(func)

Decorator; refines a handler so it’s only called on requests with an Other (TM) recipient.

facedancer.request.to_this_endpoint(func)

Decorator; refines a handler so it’s only called on requests targeting this endpoint.

facedancer.request.to_this_interface(func)

Decorator; refines a handler so it’s only called on requests targeting this interface.

facedancer.request.vendor_request_handler(**kwargs)

Decorator; declares a vendor request handler. See control_request_handler() for usage.