FreeRDP
Proxy module API

freerdp-proxy has an API for hooking/filtering certain events/messages. A module can register callbacks to events, allowing to record the data and control whether to pass/ignore, or right out drop the connection.

During startup, the proxy reads its modules from the configuration:

[Plugins]
Modules = demo,cap

These modules are loaded in a best effort manner. Additionally there is a configuration field for modules that must be loaded, so the proxy refuses to start if they are not found:

[Plugins]
Required = demo,cap

Modules must be installed as shared libraries in the <base install>/lib/freerdp3/proxy folder and match the pattern proxy-<name>-plugin.<ext> (e.g. proxy-demo-plugin.so) to be found. For security reasons loading by full path is not supported and only the installation path is used for lookup.

Currently supported hook events

Client

  • ClientInitConnect: Called before the client tries to open a connection
  • ClientUninitConnect: Called after the client has disconnected
  • ClientPreConnect: Called in client PreConnect callback
  • ClientPostConnect: Called in client PostConnect callback
  • ClientPostDisconnect: Called in client PostDisconnect callback
  • ClientX509Certificate: Called in client X509 certificate verification callback
  • ClientLoginFailure: Called in client login failure callback
  • ClientEndPaint: Called in client EndPaint callback

Server

  • ServerPostConnect: Called after a client has connected
  • ServerPeerActivate: Called after a client has activated
  • ServerChannelsInit: Called after channels are initialized
  • ServerChannelsFree: Called after channels are cleaned up
  • ServerSessionEnd: Called after the client connection disconnected

Currently supported filter events

  • KeyboardEvent: Keyboard event, e.g. all key press and release events
  • MouseEvent: Mouse event, e.g. mouse movement and button press/release events
  • ClientChannelData: Client static channel data
  • ServerChannelData: Server static channel data
  • DynamicChannelCreate: Dynamic channel create
  • ServerFetchTargetAddr: Fetch target address (e.g. RDP TargetInfo)
  • ServerPeerLogon: A peer is logging on

Developing a new module

  • Create a new file that includes freerdp/server/proxy/proxy_modules_api.h.
  • Implement the proxy_module_entry_point function and register the callbacks you are interested in.
  • Each callback receives two parameters:
    • connectionInfo* info holds connection info of the raised event.
    • void* param holds the actual event data. It should be casted by the filter to the suitable struct from filters_api.h.
  • Each callback must return a BOOL:
    • FALSE: The event will not be proxied.
    • TRUE: The event will be proxied.

A demo can be found in filter_demo.c.