Botan::PKCS11::InterfaceWrapper Class Reference

Wraps a PKCS #11 Interface object. More...

#include <p11.h>

Public Member Functions
const FunctionList &	func_2_40 () const
	Access a function list that contains all methods since PKCS #11 v.2.40.
const FunctionList30 &	func_3_0 () const
	Access a function list that contains all methods since PKCS #11 v.3.0.
const FunctionList32 &	func_3_2 () const
	Access a function list that contains all methods since PKCS #11 v.3.2.
	InterfaceWrapper (const InterfaceWrapper &)=default
	InterfaceWrapper (Interface p11_interface)
	Basic constructor using an interface.
	InterfaceWrapper (InterfaceWrapper &&)=default
std::span< const Utf8Char >	name () const
	Access the name of the interface.
InterfaceWrapper &	operator= (const InterfaceWrapper &)=default
InterfaceWrapper &	operator= (InterfaceWrapper &&)=default
const Interface &	raw_interface () const
	Access the underlying interface object.
Version	version () const
	Access the version of the interface.
	~InterfaceWrapper ()=default

Static Public Member Functions
static InterfaceWrapper	latest_p11_interface (Dynamically_Loaded_Library &library)
static Utf8Char *	p11_interface_name_ptr ()

Detailed Description

Wraps a PKCS #11 Interface object.

This class provides an interface to access PKCS #11 functions of various versions. For example func_3_0() returns the PKCS #11 v3.0 function list for a loaded interface. Only the official "PKCS 11" named interfaces are supported.

Definition at line 1283 of file p11.h.

Constructor & Destructor Documentation

InterfaceWrapper() [1/3]

Botan::PKCS11::InterfaceWrapper::InterfaceWrapper ( Interface p11_interface )

explicit

Basic constructor using an interface.

Definition at line 52 of file p11_interface.cpp.

                                                          : m_p11_interface(p11_interface) {
   if(p11_interface.pInterfaceName == nullptr || p11_interface.pFunctionList == nullptr) {
      throw PKCS11_Error("PKCS #11 interface has null pInterfaceName or pFunctionList");
   }
}

References CK_INTERFACE::pFunctionList, and CK_INTERFACE::pInterfaceName.

Referenced by InterfaceWrapper(), InterfaceWrapper(), latest_p11_interface(), operator=(), and operator=().

InterfaceWrapper() [2/3]

Botan::PKCS11::InterfaceWrapper::InterfaceWrapper ( const InterfaceWrapper & )

default

References InterfaceWrapper().

InterfaceWrapper() [3/3]

Botan::PKCS11::InterfaceWrapper::InterfaceWrapper ( InterfaceWrapper && )

default

References InterfaceWrapper().

~InterfaceWrapper()

Botan::PKCS11::InterfaceWrapper::~InterfaceWrapper ( )

default

Member Function Documentation

func_2_40()

const FunctionList & Botan::PKCS11::InterfaceWrapper::func_2_40

(

)

const

Access a function list that contains all methods since PKCS #11 v.2.40.

Definition at line 127 of file p11_interface.cpp.

                                                      {
   if(!std::ranges::equal(name(), PKCS11_INTERFACE_NAME)) {
      throw Botan::Invalid_State("Vendor defined PKCS #11 interfaces are not supported.");
   }
   return *reinterpret_cast<FunctionList*>(raw_interface().pFunctionList);
}

References name(), CK_INTERFACE::pFunctionList, and raw_interface().

func_3_0()

const FunctionList30 & Botan::PKCS11::InterfaceWrapper::func_3_0

(

)

const

Access a function list that contains all methods since PKCS #11 v.3.0.

Definition at line 134 of file p11_interface.cpp.

                                                       {
   if(!std::ranges::equal(name(), PKCS11_INTERFACE_NAME)) {
      throw Botan::Invalid_State("Vendor defined PKCS #11 interfaces are not supported.");
   }
   if(version() < Version{3, 0}) {
      throw Botan::Invalid_State("Loaded interface does not support PKCS #11 v3.0 features");
   }
   return *reinterpret_cast<FunctionList30*>(raw_interface().pFunctionList);
}

References name(), CK_INTERFACE::pFunctionList, raw_interface(), and version().

func_3_2()

const FunctionList32 & Botan::PKCS11::InterfaceWrapper::func_3_2

(

)

const

Access a function list that contains all methods since PKCS #11 v.3.2.

Definition at line 144 of file p11_interface.cpp.

                                                       {
   if(!std::ranges::equal(name(), PKCS11_INTERFACE_NAME)) {
      throw Botan::Invalid_State("Vendor defined PKCS #11 interfaces are not supported.");
   }
   if(version() < Version{3, 2}) {
      throw Botan::Invalid_State("Loaded interface does not support PKCS #11 v3.2 features");
   }
   return *reinterpret_cast<FunctionList32*>(raw_interface().pFunctionList);
}

References name(), CK_INTERFACE::pFunctionList, raw_interface(), and version().

latest_p11_interface()

InterfaceWrapper Botan::PKCS11::InterfaceWrapper::latest_p11_interface ( Dynamically_Loaded_Library & library )

static

Find the latest supported "PKCS 11" interface. Fork safe interfaces are preferred over non fork safe ones of the same version.

Definition at line 66 of file p11_interface.cpp.

                                                                                           {
   Ulong count = 0;
   auto rv = LowLevel::C_GetInterfaceList(library, nullptr, &count, nullptr);
   if(!rv) {
      // Method could not be executed. Probably due to a cryptoki library with PKCS #11 < 3.0.
      // Try the legacy C_GetFunctionList method (for PKCS#11 version 2.40).
      FunctionList* func_list = nullptr;  // NOLINT(*-const-correctness) bug in clang-tidy
      rv = LowLevel::C_GetFunctionList(library, &func_list, nullptr);
      if(!rv || func_list == nullptr) {
         throw Invalid_Argument("Failed to load function list for PKCS#11 library.");
      }
 
      return InterfaceWrapper{Interface{
         .pInterfaceName = InterfaceWrapper::p11_interface_name_ptr(),
         .pFunctionList = func_list,
         .flags = 0,
      }};
   }
   std::vector<Interface> interface_list(count);
   rv = LowLevel::C_GetInterfaceList(library, interface_list.data(), &count, nullptr);
   if(!rv) {
      // The interface list count could be computed but the interface list cannot be received. This should not happen.
      throw Invalid_Argument("Unexpected error while loading PKCS#11 interface list.");
   }
 
   // We only load interfaces named "PKCS 11" (which are the pure ones defined in the spec) with
   // version >= 2.40.
   auto is_valid_interface = [](const Interface& i) {
      if(i.pFunctionList == nullptr || i.pInterfaceName == nullptr) {
         return false;
      }
      if(!std::ranges::equal(name_of(i), PKCS11_INTERFACE_NAME)) {
         return false;
      }
      const Version version = version_of(i);
      return version >= Version{2, 40};
   };
   std::vector<Interface> valid_interfaces;
   std::copy_if(interface_list.begin(), interface_list.end(), std::back_inserter(valid_interfaces), is_valid_interface);
 
   if(valid_interfaces.empty()) {
      throw Invalid_Argument("No supported PKCS #11 interfaces found.");
   }
 
   // We prioritize valid interfaces the following way:
   // Higher versions are preferred over lower ones. If multiple interfaces of
   // the highest version exist, fork safe interfaces are preferred.
   auto priority_comparator = [](const Interface& left, const Interface& right) {
      const Version left_version = version_of(left);
      const Version right_version = version_of(right);
 
      if(left_version == right_version) {
         return (left.flags & static_cast<CK_FLAGS>(Flag::InterfaceForkSafe)) <
                (right.flags & static_cast<CK_FLAGS>(Flag::InterfaceForkSafe));
      }
      return left_version < right_version;
   };
   auto best_interface = std::max_element(valid_interfaces.begin(), valid_interfaces.end(), priority_comparator);
   return InterfaceWrapper(*best_interface);
}

References Botan::PKCS11::LowLevel::C_GetFunctionList(), Botan::PKCS11::LowLevel::C_GetInterfaceList(), CK_INTERFACE::flags, Botan::PKCS11::InterfaceForkSafe, InterfaceWrapper(), p11_interface_name_ptr(), and version().

Referenced by Botan::PKCS11::Module::reload().

name()

std::span< const Utf8Char > Botan::PKCS11::InterfaceWrapper::name

(

)

const

Access the name of the interface.

Definition at line 62 of file p11_interface.cpp.

                                                     {
   return name_of(m_p11_interface);
}

Referenced by func_2_40(), func_3_0(), and func_3_2().

operator=() [1/2]

InterfaceWrapper & Botan::PKCS11::InterfaceWrapper::operator= ( const InterfaceWrapper & )

default

References InterfaceWrapper().

operator=() [2/2]

InterfaceWrapper & Botan::PKCS11::InterfaceWrapper::operator= ( InterfaceWrapper && )

default

References InterfaceWrapper().

p11_interface_name_ptr()

Utf8Char * Botan::PKCS11::InterfaceWrapper::p11_interface_name_ptr ( )

static

Returns an immortal pointer to the Utf8Char string "PKCS 11". Used to define an interface object.

Warning

Unfortunately, the interface object requires a non constant pointer. However, this string MUST NOT be modified!

Definition at line 154 of file p11_interface.cpp.

                                                   {
   static std::array<Utf8Char, 8> STATIC_PKCS11_INTERFACE_NAME_ARR = {"PKCS 11"};
   return STATIC_PKCS11_INTERFACE_NAME_ARR.data();
}

Referenced by latest_p11_interface(), and Botan::PKCS11::LowLevel::LowLevel().

raw_interface()

const Interface & Botan::PKCS11::InterfaceWrapper::raw_interface ( ) const

inline

Access the underlying interface object.

Definition at line 1298 of file p11.h.

{ return m_p11_interface; }

Referenced by func_2_40(), func_3_0(), and func_3_2().

version()

Version Botan::PKCS11::InterfaceWrapper::version

(

)

const

Access the version of the interface.

Definition at line 58 of file p11_interface.cpp.

                                        {
   return version_of(m_p11_interface);
}

Referenced by func_3_0(), func_3_2(), and latest_p11_interface().

---

The documentation for this class was generated from the following files:

• src/lib/prov/pkcs11/p11.h
• src/lib/prov/pkcs11/p11_interface.cpp