Milestone 5: deliver embedded RDP sessions and lifecycle hardening

third_party/FreeRDP/server/proxy/modules/README.md

@@ -0,0 +1,66 @@
+# 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 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`.