Add botan_ffi_supports_api function

This lets us upgrade the FFI version over time and still allow
applications to reliably detect if the current library binary
supports their version.

As an example, it would be useful to be able to add features to FFI
sometime in 2.x. In that case, we would increase the value of the
FFI API version, even though anything calling the old API would still
work perfectly. Applications can verify at runtime the API they want to
use is supported using this new call.

4 files changed, 29 insertions, 1 deletions

diff --git a/doc/manual/ffi.rst b/doc/manual/ffi.rst
index 7a01dc8ae..b7a0d750f 100644
--- a/doc/manual/ffi.rst
+++ b/doc/manual/ffi.rst
@@ -14,7 +14,17 @@ Versioning
 
 .. cpp:function:: uint32_t botan_ffi_api_version()
 
-   Returns the FFI version
+   Returns the version of the currently supported FFI API.  This is
+   expressed in the form YYYYMMDD of the release date of this version
+   of the API.
+
+.. cpp:function int botan_ffi_supports_api(uint32_t version)
+
+   Return 0 iff the FFI version specified is supported by this
+   library. Otherwise returns -1. The expression
+   botan_ffi_supports_api(botan_ffi_api_version()) will always
+   evaluate to 0. A particular version of the library may also support
+   other (older) versions of the FFI API.
 
 .. cpp:function:: const char* botan_version_string()
 
diff --git a/src/lib/ffi/ffi.cpp b/src/lib/ffi/ffi.cpp
index 4727c0763..5c4cba4e7 100644
--- a/src/lib/ffi/ffi.cpp
+++ b/src/lib/ffi/ffi.cpp
@@ -208,6 +208,17 @@ uint32_t botan_ffi_api_version()
    return BOTAN_HAS_FFI;
    }
 
+int botan_ffi_supports_api(uint32_t api_version)
+   {
+   /*
+   * In the future if multiple versions are supported, this
+   * function would accept any of them.
+   */
+   if(api_version == BOTAN_HAS_FFI)
+      return 0;
+   return -1;
+   }
+
 const char* botan_version_string()
    {
    return Botan::version_cstr();
diff --git a/src/lib/ffi/ffi.h b/src/lib/ffi/ffi.h
index ed1b55a56..3378e0dcd 100644
--- a/src/lib/ffi/ffi.h
+++ b/src/lib/ffi/ffi.h
@@ -66,6 +66,12 @@ how to provide the cleanest API for such users would be most welcome.
 */
 BOTAN_DLL uint32_t botan_ffi_api_version();
 
+/*
+* Return 0 (ok) if the version given is one this library supports.
+* botan_ffi_supports_api(botan_ffi_api_version()) will always return 0.
+*/
+BOTAN_DLL int botan_ffi_supports_api(uint32_t api_version);
+
 BOTAN_DLL const char* botan_version_string();
 BOTAN_DLL uint32_t botan_version_major();
 BOTAN_DLL uint32_t botan_version_minor();
diff --git a/src/tests/test_ffi.cpp b/src/tests/test_ffi.cpp
index dd066e248..243583e8f 100644
--- a/src/tests/test_ffi.cpp
+++ b/src/tests/test_ffi.cpp
@@ -42,6 +42,7 @@ class FFI_Unit_Tests : public Test
          result.test_is_eq("Patch version", botan_version_patch(), Botan::version_patch());
          result.test_is_eq("Botan version", botan_version_string(), Botan::version_cstr());
          result.test_is_eq("Botan version datestamp", botan_version_datestamp(), Botan::version_datestamp());
+         result.test_is_eq("FFI supports its own version", botan_ffi_supports_api(botan_ffi_api_version()), 0);
 
          const std::vector<uint8_t> mem1 = { 0xFF, 0xAA, 0xFF };
          const std::vector<uint8_t> mem2 = mem1;