new(sinsp): support explicit ABI versioning

gnosek · gnosek · commit 815dc2dbe1bc · 2025-02-17T17:25:36.000+01:00
Introduce an explicit ABI version field to plugin_api, as well as
a size field. This allows us to explicitly detect incompatible
ABIs, but also to detect struct changes within an ABI version.

The size field is actually pretty important (maybe more than
the actual version field, as long as get_api_version can be easily
found), because it's the only way to know how big the plugin-provided
struct actually is. With plugins targeting older API versions,
we're doing a basically guaranteed out of bounds read otherwise
(if the plugin_api struct in the framework is larger than what
the plugin exports).

Signed-off-by: Grzegorz Nosek &lt;grzegorz.nosek@sysdig.com&gt;
diff --git a/userspace/libsinsp/test/events_plugin.ut.cpp b/userspace/libsinsp/test/events_plugin.ut.cpp
@@ -77,6 +77,8 @@ static ss_plugin_rc mock_plugin_next_batch(ss_plugin_t* s,
 
 static void set_mock_plugin_api(plugin_api& api) {
 	memset(&api, 0, sizeof(plugin_api));
+	api.static_plugin_abi_version = PLUGIN_ABI_VERSION;
+	api.static_plugin_api_size = sizeof(plugin_api);
 	api.get_required_api_version = mock_plugin_get_required_api_version;
 	api.get_version = mock_plugin_get_version;
 	api.get_description = mock_plugin_get_description;
diff --git a/userspace/libsinsp/test/plugins/metrics.cpp b/userspace/libsinsp/test/plugins/metrics.cpp
@@ -112,6 +112,8 @@ ss_plugin_metric* plugin_get_metrics(ss_plugin_t* s, uint32_t* num_metrics) {
 
 void get_plugin_api_sample_metrics(plugin_api& out) {
 	memset(&out, 0, sizeof(plugin_api));
+	out.static_plugin_abi_version = PLUGIN_ABI_VERSION;
+	out.static_plugin_api_size = sizeof(plugin_api);
 	out.get_required_api_version = plugin_get_required_api_version;
 	out.get_version = plugin_get_version;
 	out.get_description = plugin_get_description;
diff --git a/userspace/libsinsp/test/plugins/plugin_extract.cpp b/userspace/libsinsp/test/plugins/plugin_extract.cpp
@@ -157,6 +157,8 @@ ss_plugin_rc plugin_set_config(ss_plugin_t* s, const ss_plugin_set_config_input*
 
 void get_plugin_api_sample_plugin_extract(plugin_api& out) {
 	memset(&out, 0, sizeof(plugin_api));
+	out.static_plugin_abi_version = PLUGIN_ABI_VERSION;
+	out.static_plugin_api_size = sizeof(plugin_api);
 	out.get_required_api_version = plugin_get_required_api_version;
 	out.get_version = plugin_get_version;
 	out.get_description = plugin_get_description;
diff --git a/userspace/libsinsp/test/plugins/plugin_source.cpp b/userspace/libsinsp/test/plugins/plugin_source.cpp
@@ -155,6 +155,8 @@ ss_plugin_rc plugin_next_batch(ss_plugin_t* s,
 
 void get_plugin_api_sample_plugin_source(plugin_api& out) {
 	memset(&out, 0, sizeof(plugin_api));
+	out.static_plugin_abi_version = PLUGIN_ABI_VERSION;
+	out.static_plugin_api_size = sizeof(plugin_api);
 	out.get_required_api_version = plugin_get_required_api_version;
 	out.get_version = plugin_get_version;
 	out.get_description = plugin_get_description;
diff --git a/userspace/libsinsp/test/plugins/routines.cpp b/userspace/libsinsp/test/plugins/routines.cpp
@@ -140,6 +140,8 @@ static ss_plugin_rc plugin_capture_close(ss_plugin_t* s, const ss_plugin_capture
 
 void get_plugin_api_sample_routines(plugin_api& out) {
 	memset(&out, 0, sizeof(plugin_api));
+	out.static_plugin_abi_version = PLUGIN_ABI_VERSION;
+	out.static_plugin_api_size = sizeof(plugin_api);
 	out.get_required_api_version = plugin_get_required_api_version;
 	out.get_version = plugin_get_version;
 	out.get_description = plugin_get_description;
diff --git a/userspace/libsinsp/test/plugins/syscall_async.cpp b/userspace/libsinsp/test/plugins/syscall_async.cpp
@@ -229,6 +229,8 @@ ss_plugin_rc plugin_dump_state(ss_plugin_t* s,
 
 void get_plugin_api_sample_syscall_async(plugin_api& out) {
 	memset(&out, 0, sizeof(plugin_api));
+	out.static_plugin_abi_version = PLUGIN_ABI_VERSION;
+	out.static_plugin_api_size = sizeof(plugin_api);
 	out.get_required_api_version = plugin_get_required_api_version;
 	out.get_version = plugin_get_version;
 	out.get_description = plugin_get_description;
diff --git a/userspace/libsinsp/test/plugins/syscall_extract.cpp b/userspace/libsinsp/test/plugins/syscall_extract.cpp
@@ -372,6 +372,8 @@ ss_plugin_rc plugin_extract_fields(ss_plugin_t* s,
 
 void get_plugin_api_sample_syscall_extract(plugin_api& out) {
 	memset(&out, 0, sizeof(plugin_api));
+	out.static_plugin_abi_version = PLUGIN_ABI_VERSION;
+	out.static_plugin_api_size = sizeof(plugin_api);
 	out.get_required_api_version = plugin_get_required_api_version;
 	out.get_version = plugin_get_version;
 	out.get_description = plugin_get_description;
diff --git a/userspace/libsinsp/test/plugins/syscall_parse.cpp b/userspace/libsinsp/test/plugins/syscall_parse.cpp
@@ -257,6 +257,8 @@ ss_plugin_rc plugin_parse_event(ss_plugin_t* s,
 
 void get_plugin_api_sample_syscall_parse(plugin_api& out) {
 	memset(&out, 0, sizeof(plugin_api));
+	out.static_plugin_abi_version = PLUGIN_ABI_VERSION;
+	out.static_plugin_api_size = sizeof(plugin_api);
 	out.get_required_api_version = plugin_get_required_api_version;
 	out.get_version = plugin_get_version;
 	out.get_description = plugin_get_description;
diff --git a/userspace/libsinsp/test/plugins/syscall_source.cpp b/userspace/libsinsp/test/plugins/syscall_source.cpp
@@ -149,6 +149,8 @@ ss_plugin_rc plugin_next_batch(ss_plugin_t* s,
 
 void get_plugin_api_sample_syscall_source(plugin_api& out) {
 	memset(&out, 0, sizeof(plugin_api));
+	out.static_plugin_abi_version = PLUGIN_ABI_VERSION;
+	out.static_plugin_api_size = sizeof(plugin_api);
 	out.get_required_api_version = plugin_get_required_api_version;
 	out.get_version = plugin_get_version;
 	out.get_description = plugin_get_description;
diff --git a/userspace/libsinsp/test/plugins/syscall_subtables.cpp b/userspace/libsinsp/test/plugins/syscall_subtables.cpp
@@ -275,6 +275,8 @@ ss_plugin_rc plugin_parse_event(ss_plugin_t* s,
 
 void get_plugin_api_sample_syscall_subtables(plugin_api& out) {
 	memset(&out, 0, sizeof(plugin_api));
+	out.static_plugin_abi_version = PLUGIN_ABI_VERSION;
+	out.static_plugin_api_size = sizeof(plugin_api);
 	out.get_required_api_version = plugin_get_required_api_version;
 	out.get_version = plugin_get_version;
 	out.get_description = plugin_get_description;
diff --git a/userspace/libsinsp/test/plugins/syscall_subtables_array.cpp b/userspace/libsinsp/test/plugins/syscall_subtables_array.cpp
@@ -260,6 +260,8 @@ ss_plugin_rc plugin_parse_event(ss_plugin_t* s,
 
 void get_plugin_api_sample_syscall_subtables_array(plugin_api& out) {
 	memset(&out, 0, sizeof(plugin_api));
+	out.static_plugin_abi_version = PLUGIN_ABI_VERSION;
+	out.static_plugin_api_size = sizeof(plugin_api);
 	out.get_required_api_version = plugin_get_required_api_version;
 	out.get_version = plugin_get_version;
 	out.get_description = plugin_get_description;
diff --git a/userspace/libsinsp/test/plugins/syscall_subtables_array_pair.cpp b/userspace/libsinsp/test/plugins/syscall_subtables_array_pair.cpp
@@ -301,6 +301,8 @@ ss_plugin_rc plugin_parse_event(ss_plugin_t* s,
 
 void get_plugin_api_sample_syscall_subtables_array_pair(plugin_api& out) {
 	memset(&out, 0, sizeof(plugin_api));
+	out.static_plugin_abi_version = PLUGIN_ABI_VERSION;
+	out.static_plugin_api_size = sizeof(plugin_api);
 	out.get_required_api_version = plugin_get_required_api_version;
 	out.get_version = plugin_get_version;
 	out.get_description = plugin_get_description;
diff --git a/userspace/libsinsp/test/plugins/syscall_tables.cpp b/userspace/libsinsp/test/plugins/syscall_tables.cpp
@@ -618,6 +618,8 @@ ss_plugin_rc plugin_parse_event(ss_plugin_t* s,
 
 void get_plugin_api_sample_syscall_tables(plugin_api& out) {
 	memset(&out, 0, sizeof(plugin_api));
+	out.static_plugin_abi_version = PLUGIN_ABI_VERSION;
+	out.static_plugin_api_size = sizeof(plugin_api);
 	out.get_required_api_version = plugin_get_required_api_version;
 	out.get_version = plugin_get_version;
 	out.get_description = plugin_get_description;
diff --git a/userspace/plugin/plugin_abi.h b/userspace/plugin/plugin_abi.h
@@ -1,71 +1,75 @@
 #ifndef PLUGIN_ABI_VERSION
-#define PLUGIN_ABI_VERSION 3
+#define PLUGIN_ABI_VERSION 4
 #if defined(__linux__) && defined(__x86_64__) && (defined(__GNUC__) || (__STDC_VERSION__ >= 201112L))
 #include <assert.h>
 #include <stddef.h>
+static_assert(sizeof(((plugin_api*)0)->static_plugin_abi_version) == 8, "static_plugin_abi_version size mismatch");
+static_assert(offsetof(plugin_api, static_plugin_abi_version) == 0, "static_plugin_abi_version offset mismatch");
+static_assert(sizeof(((plugin_api*)0)->static_plugin_api_size) == 8, "static_plugin_api_size size mismatch");
+static_assert(offsetof(plugin_api, static_plugin_api_size) == 8, "static_plugin_api_size offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_required_api_version) == 8, "get_required_api_version size mismatch");
-static_assert(offsetof(plugin_api, get_required_api_version) == 0, "get_required_api_version offset mismatch");
+static_assert(offsetof(plugin_api, get_required_api_version) == 16, "get_required_api_version offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_init_schema) == 8, "get_init_schema size mismatch");
-static_assert(offsetof(plugin_api, get_init_schema) == 8, "get_init_schema offset mismatch");
+static_assert(offsetof(plugin_api, get_init_schema) == 24, "get_init_schema offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->init) == 8, "init size mismatch");
-static_assert(offsetof(plugin_api, init) == 16, "init offset mismatch");
+static_assert(offsetof(plugin_api, init) == 32, "init offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->destroy) == 8, "destroy size mismatch");
-static_assert(offsetof(plugin_api, destroy) == 24, "destroy offset mismatch");
+static_assert(offsetof(plugin_api, destroy) == 40, "destroy offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_last_error) == 8, "get_last_error size mismatch");
-static_assert(offsetof(plugin_api, get_last_error) == 32, "get_last_error offset mismatch");
+static_assert(offsetof(plugin_api, get_last_error) == 48, "get_last_error offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_name) == 8, "get_name size mismatch");
-static_assert(offsetof(plugin_api, get_name) == 40, "get_name offset mismatch");
+static_assert(offsetof(plugin_api, get_name) == 56, "get_name offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_description) == 8, "get_description size mismatch");
-static_assert(offsetof(plugin_api, get_description) == 48, "get_description offset mismatch");
+static_assert(offsetof(plugin_api, get_description) == 64, "get_description offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_contact) == 8, "get_contact size mismatch");
-static_assert(offsetof(plugin_api, get_contact) == 56, "get_contact offset mismatch");
+static_assert(offsetof(plugin_api, get_contact) == 72, "get_contact offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_version) == 8, "get_version size mismatch");
-static_assert(offsetof(plugin_api, get_version) == 64, "get_version offset mismatch");
+static_assert(offsetof(plugin_api, get_version) == 80, "get_version offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_id) == 8, "get_id size mismatch");
-static_assert(offsetof(plugin_api, get_id) == 72, "get_id offset mismatch");
+static_assert(offsetof(plugin_api, get_id) == 88, "get_id offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_event_source) == 8, "get_event_source size mismatch");
-static_assert(offsetof(plugin_api, get_event_source) == 80, "get_event_source offset mismatch");
+static_assert(offsetof(plugin_api, get_event_source) == 96, "get_event_source offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->open) == 8, "open size mismatch");
-static_assert(offsetof(plugin_api, open) == 88, "open offset mismatch");
+static_assert(offsetof(plugin_api, open) == 104, "open offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->close) == 8, "close size mismatch");
-static_assert(offsetof(plugin_api, close) == 96, "close offset mismatch");
+static_assert(offsetof(plugin_api, close) == 112, "close offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->list_open_params) == 8, "list_open_params size mismatch");
-static_assert(offsetof(plugin_api, list_open_params) == 104, "list_open_params offset mismatch");
+static_assert(offsetof(plugin_api, list_open_params) == 120, "list_open_params offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_progress) == 8, "get_progress size mismatch");
-static_assert(offsetof(plugin_api, get_progress) == 112, "get_progress offset mismatch");
+static_assert(offsetof(plugin_api, get_progress) == 128, "get_progress offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->event_to_string) == 8, "event_to_string size mismatch");
-static_assert(offsetof(plugin_api, event_to_string) == 120, "event_to_string offset mismatch");
+static_assert(offsetof(plugin_api, event_to_string) == 136, "event_to_string offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->next_batch) == 8, "next_batch size mismatch");
-static_assert(offsetof(plugin_api, next_batch) == 128, "next_batch offset mismatch");
+static_assert(offsetof(plugin_api, next_batch) == 144, "next_batch offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_extract_event_types) == 8, "get_extract_event_types size mismatch");
-static_assert(offsetof(plugin_api, get_extract_event_types) == 136, "get_extract_event_types offset mismatch");
+static_assert(offsetof(plugin_api, get_extract_event_types) == 152, "get_extract_event_types offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_extract_event_sources) == 8, "get_extract_event_sources size mismatch");
-static_assert(offsetof(plugin_api, get_extract_event_sources) == 144, "get_extract_event_sources offset mismatch");
+static_assert(offsetof(plugin_api, get_extract_event_sources) == 160, "get_extract_event_sources offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_fields) == 8, "get_fields size mismatch");
-static_assert(offsetof(plugin_api, get_fields) == 152, "get_fields offset mismatch");
+static_assert(offsetof(plugin_api, get_fields) == 168, "get_fields offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->extract_fields) == 8, "extract_fields size mismatch");
-static_assert(offsetof(plugin_api, extract_fields) == 160, "extract_fields offset mismatch");
+static_assert(offsetof(plugin_api, extract_fields) == 176, "extract_fields offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_parse_event_types) == 8, "get_parse_event_types size mismatch");
-static_assert(offsetof(plugin_api, get_parse_event_types) == 168, "get_parse_event_types offset mismatch");
+static_assert(offsetof(plugin_api, get_parse_event_types) == 184, "get_parse_event_types offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_parse_event_sources) == 8, "get_parse_event_sources size mismatch");
-static_assert(offsetof(plugin_api, get_parse_event_sources) == 176, "get_parse_event_sources offset mismatch");
+static_assert(offsetof(plugin_api, get_parse_event_sources) == 192, "get_parse_event_sources offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->parse_event) == 8, "parse_event size mismatch");
-static_assert(offsetof(plugin_api, parse_event) == 184, "parse_event offset mismatch");
+static_assert(offsetof(plugin_api, parse_event) == 200, "parse_event offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_async_event_sources) == 8, "get_async_event_sources size mismatch");
-static_assert(offsetof(plugin_api, get_async_event_sources) == 192, "get_async_event_sources offset mismatch");
+static_assert(offsetof(plugin_api, get_async_event_sources) == 208, "get_async_event_sources offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_async_events) == 8, "get_async_events size mismatch");
-static_assert(offsetof(plugin_api, get_async_events) == 200, "get_async_events offset mismatch");
+static_assert(offsetof(plugin_api, get_async_events) == 216, "get_async_events offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->set_async_event_handler) == 8, "set_async_event_handler size mismatch");
-static_assert(offsetof(plugin_api, set_async_event_handler) == 208, "set_async_event_handler offset mismatch");
+static_assert(offsetof(plugin_api, set_async_event_handler) == 224, "set_async_event_handler offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->dump_state) == 8, "dump_state size mismatch");
-static_assert(offsetof(plugin_api, dump_state) == 216, "dump_state offset mismatch");
+static_assert(offsetof(plugin_api, dump_state) == 232, "dump_state offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->set_config) == 8, "set_config size mismatch");
-static_assert(offsetof(plugin_api, set_config) == 224, "set_config offset mismatch");
+static_assert(offsetof(plugin_api, set_config) == 240, "set_config offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->get_metrics) == 8, "get_metrics size mismatch");
-static_assert(offsetof(plugin_api, get_metrics) == 232, "get_metrics offset mismatch");
+static_assert(offsetof(plugin_api, get_metrics) == 248, "get_metrics offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->capture_open) == 8, "capture_open size mismatch");
-static_assert(offsetof(plugin_api, capture_open) == 240, "capture_open offset mismatch");
+static_assert(offsetof(plugin_api, capture_open) == 256, "capture_open offset mismatch");
 static_assert(sizeof(((plugin_api*)0)->capture_close) == 8, "capture_close size mismatch");
-static_assert(offsetof(plugin_api, capture_close) == 248, "capture_close offset mismatch");
+static_assert(offsetof(plugin_api, capture_close) == 264, "capture_close offset mismatch");
 #endif
 #endif
diff --git a/userspace/plugin/plugin_api.h b/userspace/plugin/plugin_api.h
@@ -19,6 +19,7 @@ limitations under the License.
 #pragma once
 
 #include <plugin/plugin_types.h>
+#include <stddef.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -531,6 +532,10 @@ typedef ss_plugin_rc (*ss_plugin_async_event_handler_t)(ss_plugin_owner_t* o,
 // Plugins API vtable
 //
 typedef struct {
+	size_t static_plugin_abi_version;
+
+	size_t static_plugin_api_size;
+
 	//
 	// Return the version of the plugin API used by this plugin.
 	// Required: yes
diff --git a/userspace/plugin/plugin_loader.c b/userspace/plugin/plugin_loader.c
@@ -131,36 +131,46 @@ plugin_handle_t* plugin_load(const char* path, char* err) {
 	return ret;
 }
 
-plugin_handle_t* plugin_load_api(const plugin_api* api, char* err) {
-	// alloc and init memory
-	err[0] = '\0';
-	if(!api) {
-		strlcpy(err, "can't allocate plugin handle with invalid API table", PLUGIN_MAX_ERRLEN);
-		return NULL;
+static bool plugin_copy_versioned_api(plugin_api* dst, const plugin_api* src, char* err) {
+	// first, check the ABI version
+	if(src->static_plugin_abi_version != PLUGIN_ABI_VERSION) {
+		snprintf(err,
+		         PLUGIN_MAX_ERRLEN,
+		         "unsupported plugin ABI version: %zu",
+		         src->static_plugin_abi_version);
+		return false;
 	}
 
-	plugin_handle_t* ret = (plugin_handle_t*)calloc(1, sizeof(plugin_handle_t));
-	if(!ret) {
-		strlcpy(err, "error allocating plugin handle", PLUGIN_MAX_ERRLEN);
-		return NULL;
+	// then, copy the whole struct to the right place
+	size_t size = sizeof(plugin_api);
+	if(size > src->static_plugin_api_size) {
+		size = src->static_plugin_api_size;
 	}
-	ret->api = *api;
+	memcpy(dst, src, size);
+	return true;
+}
+
+static bool plugin_copy_legacy_api(plugin_api* dst, const plugin_api* src, char* err) {
+	// first, copy the whole struct to the right place
+	memcpy(&dst->get_required_api_version,
+	       &src->get_required_api_version,
+	       sizeof(plugin_api) - offsetof(plugin_api, get_required_api_version));
 
-	// todo: remove this if/when we get to API version 4
+	// then, check the API version (3.10 changed the plugin_api layout)
+	// todo: remove this if/when we drop API < 3.10 compatibility
 	uint32_t major, minor, patch;
-	const char* ver;
-	if(api->get_required_api_version == NULL) {
+	if(dst->get_required_api_version == NULL) {
 		strlcpy(err, "plugin_get_required_api_version symbol not implemented", PLUGIN_MAX_ERRLEN);
-		return NULL;
+		return false;
 	}
 
-	ver = api->get_required_api_version();
+	const char* ver = dst->get_required_api_version();
 	if(sscanf(ver, "%" PRIu32 ".%" PRIu32 ".%" PRIu32, &major, &minor, &patch) != 3) {
 		snprintf(err,
 		         PLUGIN_MAX_ERRLEN,
 		         "plugin provided an invalid required API version: '%s'",
 		         ver);
-		return NULL;
+		return false;
 	}
 
 	// API 3.10 introduced dump_state in the middle of the plugin_api struct.
@@ -169,9 +179,42 @@ plugin_handle_t* plugin_load_api(const plugin_api* api, char* err) {
 		size_t from_offset = offsetof(plugin_api, dump_state);
 		size_t to_offset = offsetof(plugin_api, set_config);
 		size_t size = sizeof(plugin_api) - to_offset;
-		char* api_ptr = (char*)&ret->api;
+		char* api_ptr = (char*)dst;
 		memmove(api_ptr + to_offset, api_ptr + from_offset, size);
-		ret->api.dump_state = NULL;
+		dst->dump_state = NULL;
+	}
+
+	return true;
+}
+
+plugin_handle_t* plugin_load_api(const plugin_api* api, char* err) {
+	// alloc and init memory
+	err[0] = '\0';
+	if(!api) {
+		strlcpy(err, "can't allocate plugin handle with invalid API table", PLUGIN_MAX_ERRLEN);
+		return NULL;
+	}
+
+	plugin_handle_t* ret = (plugin_handle_t*)calloc(1, sizeof(plugin_handle_t));
+	if(!ret) {
+		strlcpy(err, "error allocating plugin handle", PLUGIN_MAX_ERRLEN);
+		return NULL;
+	}
+
+	// we're *very* conservative here with potentially valid pointer values, but anything below
+	// 4096 just cannot be a valid address on any architecture we support
+	bool plugin_api_copied;
+	if(api->static_plugin_abi_version > 4096) {
+		// the first member is a function pointer, so the whole struct is unversioned
+		plugin_api_copied = plugin_copy_legacy_api(&ret->api, api, err);
+	} else {
+		// the first member cannot be a function pointer, so it's a version number
+		plugin_api_copied = plugin_copy_versioned_api(&ret->api, api, err);
+	}
+
+	if(!plugin_api_copied) {
+		free(ret);
+		return NULL;
 	}
 
 	return ret;
