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.