Crate openvpn_plugin

openvpn-plugin is a crate that makes it easy to write OpenVPN plugins in Rust.

The crate contains two main things:

• The openvpn_plugin! macro for generating the FFI interface OpenVPN will interact with
• The FFI and safe Rust types needed to communicate with OpenVPN.

Usage

Edit your Cargo.toml to depend on this crate and set the type of your crate to a cdylib in order to make it compile to a shared library that OpenVPN will understand:

[lib]
crate-type = ["cdylib"]

[dependencies]
openvpn-plugin = "0.1"

Import the crate, including macros, in your crate root (lib.rs):

#[macro_use] extern crate openvpn_plugin;

Also in your crate root (lib.rs) define your handle type, the three callback functions and call the openvpn_plugin! macro to generate the corresponding FFI bindings. More details on the handle and the callback functions can be found in the documentation for the openvpn_plugin! macro.

pub struct Handle {
    // Fields needed for the plugin to keep state between callbacks
}

fn openvpn_open(
    args: &[CString],
    env: &HashMap<CString, CString>,
) -> Result<(Vec<openvpn_plugin::types::OpenVpnPluginEvent>, Handle), ::std::io::Error> {
    // Listen to only the `Up` event, which will be fired when a tunnel has been established.
    let events = vec![OpenVpnPluginEvent::Up];
    // Create the handle instance.
    let handle = Handle { /* ... */ };
    Ok((events, handle))
}

pub fn openvpn_close(handle: Handle) {
    println!("Plugin is closing down");
}

fn openvpn_event(
    event: openvpn_plugin::types::OpenVpnPluginEvent,
    args: &[CString],
    env: &HashMap<CString, CString>,
    handle: &mut Handle,
) -> Result<EventResult, ::std::io::Error> {
    /* Process the event */

    // If the processing worked fine and/or the request the callback represents should be
    // accepted, return `EventResult::Success`. See docs on this enum for more info.
    Ok(EventResult::Success)
}

openvpn_plugin!(::openvpn_open, ::openvpn_close, ::openvpn_event, Handle);

Modules

ffi	FFI types and functions used by the plugin to convert between the types OpenVPN pass and expect back and the Rust types the plugin will be exposed to.
logging	Functions for logging errors that occur in plugins.
types	Rust types representing values and instructions from and to OpenVPN. Intended to be the safe abstraction exposed to the plugins. Constants for OpenVPN. Taken from include/openvpn-plugin.h in the OpenVPN repository: https://github.com/OpenVPN/openvpn/blob/master/include/openvpn-plugin.h.in

Macros

openvpn_plugin

The main part of this crate. The macro generates the public FFI functions that OpenVPN looks for in a shared library: