[−][src]Macro openvpn_plugin::openvpn_plugin
The main part of this crate. The macro generates the public FFI functions that OpenVPN looks for in a shared library:
openvpn_plugin_open_v3
- Will call$open_fn
openvpn_plugin_close_v1
- Will call$close_fn
openvpn_plugin_func_v3
- Will call$event_fn
This macro must be called in the crate root of the crate you wish to become an OpenVPN plugin. That is because the FFI functions must be publicly exported from the shared library for OpenVPN to find them.
See the top level library documentation and the included debug-plugin
crate for examples on
how to use this macro.
$open_fn
- The plugin load callback
Should be a function with the following signature:
fn foo_open( args: Vec<CString>, env: HashMap<CString, CString> ) -> Result<(Vec<EventType>, Handle), Error> { /// ... }
With foo_open
substituted for a function name of your liking and Handle
being the
$handle_ty
handle type you pass.
The type of the error in the result from this function does not matter, as long as it implements
std::error::Error
. Any error returned is logged and then OPENVPN_PLUGIN_FUNC_ERROR
is returned to OpenVPN, which indicates that the plugin failed to load and OpenVPN will abort
and exit.
This function will be called by OpenVPN when the plugin is loaded, just as OpenVPN starts.
This function has access to the arguments passed to the plugin and the initial OpenVPN environment. If the plugin deems the open operation successful it should return a vector with the events it wants to register for and the handle instance that the plugin can use to keep state (See further down for more on the handle).
The openvpn_plugin::ffi::parse::{string_array_utf8, env_utf8}
functions can be used to try
to convert the arguments and environment into Rust String
s.
$close_fn
- The plugin unload callback
Should be a function with the following signature:
fn foo_close(handle: Handle) { /// ... }
With foo_close
substituted for a function name of your liking and Handle
being the
$handle_ty
handle type you pass.
This function is called just before the plugin is unloaded, just before OpenVPN shuts down. Here the plugin can do any cleaning up that is necessary. Since the handle is passed by value it will be dropped when this function returns.
$event_fn
- The event callback function
Should be a function with the following signature:
fn foo_event( event: EventType, args: Vec<CString>, env: HashMap<CString, CString>, handle: &mut Handle, ) -> Result<EventResult, Error> { /// ... }
With foo_event
substituted for a function name of your liking and Handle
being the
$handle_ty
handle type you pass.
The type of the error in the result from this function does not matter, as long as it implements
std::error::Error
. Any error returned is logged and then OPENVPN_PLUGIN_FUNC_ERROR
is returned to OpenVPN. OPENVPN_PLUGIN_FUNC_ERROR
indicates different things on different
events. In the case of an authentication request or TLS key verification it means that the
request is denied and the connection is aborted.
This function is being called by OpenVPN each time one of the events that $open_fn
registered
for happens. This can for example be that a tunnel is established or that a client wants to
authenticate.
The first argument, EventType
, will tell which event that is happening.
$handle_ty
- The handle type
The handle must be created and returned by the $open_fn
function and will be kept for the
entire runtime of the plugin. The handle is passed to every subsequent callback and this is the
way that the plugin is supposed to keep state between each callback.
The handle instance is being dropped upon return from the $close_fn
function just as the
plugin is being unloaded.