976c3c2ab9
* Split out proxy headers and moved to public API to allow external modules to be built. * Split proxy into proxy library and proxy binary. The library can be used by other applications and provides a simple API * Improved channel passthrough, now all channels including dynamic channels work. * Extended module API to hook more events, improved module samples * Cleaned up proxy code, removed global static variables used, added WINPR_ASSERT
67 lines
2.8 KiB
Markdown
67 lines
2.8 KiB
Markdown
# 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:
|
|
|
|
```ini
|
|
[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:
|
|
|
|
```ini
|
|
[Plugins]
|
|
Required = demo,cap
|
|
```
|
|
|
|
Modules must be installed as shared libraris 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`.
|