Botan::PKCS11::MechanismWrapper Class Reference

#include <p11_mechanism.h>

Classes
union	MechanismParameters
	Holds the mechanism parameters for OAEP, PSS and ECDH. More...

Public Member Functions
Mechanism *	data () const
MechanismType	mechanism_type () const
	MechanismWrapper (MechanismType mechanism_type)
size_t	padding_size () const
void	set_ecdh_other_key (const uint8_t other_key[], size_t other_key_len)
void	set_ecdh_salt (const uint8_t salt[], size_t salt_len)

Static Public Member Functions
static MechanismWrapper	create_ecdh_mechanism (std::string_view params)
static MechanismWrapper	create_ecdsa_mechanism (std::string_view hash)
static MechanismWrapper	create_rsa_crypt_mechanism (std::string_view padding)
static MechanismWrapper	create_rsa_sign_mechanism (std::string_view padding)

Detailed Description

Simple class to build and hold the data for a CK_MECHANISM struct for RSA (encryption/decryption, signature/verification) and EC (ECDSA signature/verification, ECDH key derivation).

Definition at line 26 of file p11_mechanism.h.

Constructor & Destructor Documentation

MechanismWrapper()

Botan::PKCS11::MechanismWrapper::MechanismWrapper ( MechanismType mechanism_type )

explicit

Parameters

mechanism_type

the CK_MECHANISM_TYPE for the mechanism field of the CK_MECHANISM struct

Definition at line 180 of file p11_mechanism.cpp.

                                                               :
      m_mechanism({static_cast<CK_MECHANISM_TYPE>(mechanism_type), nullptr, 0}), m_parameters(nullptr) {}

References mechanism_type().

Referenced by create_ecdsa_mechanism().

Member Function Documentation

create_ecdh_mechanism()

MechanismWrapper Botan::PKCS11::MechanismWrapper::create_ecdh_mechanism ( std::string_view params )

static

Creates the CK_MECHANISM data for ECDH key derivation (CKM_ECDH1_DERIVE or CKM_ECDH1_COFACTOR_DERIVE)

Parameters

params

specifies the key derivation function to use. Supported KDFs are Raw and SHA-1 to SHA-512. Params can also include the string "Cofactor" if the cofactor key derivation mechanism should be used, for example "SHA-512,Cofactor"

Definition at line 247 of file p11_mechanism.cpp.

                                                                              {
   std::vector<std::string> param_parts = split_on(params, ',');
 
   if(param_parts.empty() || param_parts.size() > 2) {
      throw Invalid_Argument(fmt("PKCS #11 ECDH key derivation bad params {}", params));
   }
 
   const bool use_cofactor =
      (param_parts[0] == "Cofactor") || (param_parts.size() == 2 && param_parts[1] == "Cofactor");
 
   std::string kdf_name = (param_parts[0] == "Cofactor" ? param_parts[1] : param_parts[0]);
   std::string hash = kdf_name;
 
   if(kdf_name != "Raw") {
      SCAN_Name kdf_hash(kdf_name);
 
      if(kdf_hash.arg_count() > 0) {
         hash = kdf_hash.arg(0);
      }
   }
 
   auto kdf = EcdhHash.find(hash);
   if(kdf == EcdhHash.end()) {
      throw Lookup_Error("PKCS#11 ECDH key derivation does not support KDF " + kdf_name);
   }
   MechanismWrapper mech(use_cofactor ? MechanismType::Ecdh1CofactorDerive : MechanismType::Ecdh1Derive);
   mech.m_parameters = std::make_shared<MechanismParameters>();
   mech.m_parameters->ecdh_params.kdf = static_cast<CK_EC_KDF_TYPE>(kdf->second);
   mech.m_mechanism.pParameter = mech.m_parameters.get();
   mech.m_mechanism.ulParameterLen = sizeof(Ecdh1DeriveParams);
   return mech;
}

References Botan::SCAN_Name::arg(), Botan::SCAN_Name::arg_count(), Botan::PKCS11::Ecdh1CofactorDerive, Botan::PKCS11::Ecdh1Derive, Botan::fmt(), CK_MECHANISM::pParameter, Botan::split_on(), and CK_MECHANISM::ulParameterLen.

create_ecdsa_mechanism()

MechanismWrapper Botan::PKCS11::MechanismWrapper::create_ecdsa_mechanism ( std::string_view hash )

static

Creates the CK_MECHANISM data for ECDSA signature/verification

Parameters

hash	the hash algorithm used to hash the data to sign. supported hash functions are Raw and SHA-1 to SHA-512

Definition at line 228 of file p11_mechanism.cpp.

                                                                                       {
   const std::string hash_spec(hash_spec_view);
   auto mechanism = EcdsaHash.find(hash_spec);
   if(mechanism != EcdsaHash.end()) {
      return MechanismWrapper(mechanism->second);
   }
 
   SCAN_Name req(hash_spec);
 
   if(req.algo_name() == "EMSA1" && req.arg_count() == 1) {
      mechanism = EcdsaHash.find(req.arg(0));
      if(mechanism != EcdsaHash.end()) {
         return MechanismWrapper(mechanism->second);
      }
   }
 
   throw Lookup_Error(fmt("PKCS #11 ECDSA sign/verify does not support {}", hash_spec));
}

References Botan::SCAN_Name::algo_name(), Botan::SCAN_Name::arg(), Botan::SCAN_Name::arg_count(), Botan::fmt(), and MechanismWrapper().

create_rsa_crypt_mechanism()

MechanismWrapper Botan::PKCS11::MechanismWrapper::create_rsa_crypt_mechanism ( std::string_view padding )

static

Creates the CK_MECHANISM data for RSA encryption/decryption

Parameters

padding

supported paddings are Raw (X.509), EME-PKCS1-v1_5 (PKCS#1 v1.5) and OAEP (PKCS#1 OAEP)

Definition at line 183 of file p11_mechanism.cpp.

                                                                                         {
   const std::string padding(padding_view);
   auto mechanism_info_it = CryptMechanisms.find(padding);
   if(mechanism_info_it == CryptMechanisms.end()) {
      // at this point it would be possible to support additional configurations that are not predefined above by parsing `padding`
      throw Lookup_Error("PKCS#11 RSA encrypt/decrypt does not support EME " + padding);
   }
   RSA_CryptMechanism mechanism_info = mechanism_info_it->second;
 
   MechanismWrapper mech(mechanism_info.type());
   if(mechanism_info.type() == MechanismType::RsaPkcsOaep) {
      mech.m_parameters = std::make_shared<MechanismParameters>();
      mech.m_parameters->oaep_params.hashAlg = static_cast<CK_MECHANISM_TYPE>(mechanism_info.hash());
      mech.m_parameters->oaep_params.mgf = static_cast<CK_RSA_PKCS_MGF_TYPE>(mechanism_info.mgf());
      mech.m_parameters->oaep_params.source = CKZ_DATA_SPECIFIED;
      mech.m_parameters->oaep_params.pSourceData = nullptr;
      mech.m_parameters->oaep_params.ulSourceDataLen = 0;
      mech.m_mechanism.pParameter = mech.m_parameters.get();
      mech.m_mechanism.ulParameterLen = sizeof(RsaPkcsOaepParams);
   }
   mech.m_padding_size = mechanism_info.padding_size();
   return mech;
}

References CKZ_DATA_SPECIFIED, CK_MECHANISM::pParameter, Botan::PKCS11::RsaPkcsOaep, and CK_MECHANISM::ulParameterLen.

create_rsa_sign_mechanism()

MechanismWrapper Botan::PKCS11::MechanismWrapper::create_rsa_sign_mechanism ( std::string_view padding )

static

Creates the CK_MECHANISM data for RSA signature/verification

Parameters

padding

supported paddings are Raw (X.509), EMSA3 (PKCS#1 v1.5), EMSA4 (PKCS#1 PSS), EMSA2 (ANSI X9.31) and ISO9796 (ISO/IEC 9796)

Definition at line 207 of file p11_mechanism.cpp.

                                                                                        {
   const std::string padding(padding_view);
   auto mechanism_info_it = SignMechanisms.find(padding);
   if(mechanism_info_it == SignMechanisms.end()) {
      // at this point it would be possible to support additional configurations that are not predefined above by parsing `padding`
      throw Lookup_Error("PKCS#11 RSA sign/verify does not support EMSA " + padding);
   }
   RSA_SignMechanism mechanism_info = mechanism_info_it->second;
 
   MechanismWrapper mech(mechanism_info.type());
   if(PssOptions.find(mechanism_info.type()) != PssOptions.end()) {
      mech.m_parameters = std::make_shared<MechanismParameters>();
      mech.m_parameters->pss_params.hashAlg = static_cast<CK_MECHANISM_TYPE>(mechanism_info.hash());
      mech.m_parameters->pss_params.mgf = static_cast<CK_RSA_PKCS_MGF_TYPE>(mechanism_info.mgf());
      mech.m_parameters->pss_params.sLen = static_cast<Ulong>(mechanism_info.salt_size());
      mech.m_mechanism.pParameter = mech.m_parameters.get();
      mech.m_mechanism.ulParameterLen = sizeof(RsaPkcsPssParams);
   }
   return mech;
}

References CK_MECHANISM::pParameter, and CK_MECHANISM::ulParameterLen.

data()

Mechanism * Botan::PKCS11::MechanismWrapper::data ( ) const

inline

Returns

a pointer to the CK_MECHANISM struct that can be passed to the cryptoki functions

Definition at line 81 of file p11_mechanism.h.

{ return const_cast<Mechanism*>(&m_mechanism); }

mechanism_type()

MechanismType Botan::PKCS11::MechanismWrapper::mechanism_type ( ) const

inline

Definition at line 83 of file p11_mechanism.h.

{ return static_cast<MechanismType>(m_mechanism.mechanism); }

References CK_MECHANISM::mechanism.

Referenced by MechanismWrapper().

padding_size()

size_t Botan::PKCS11::MechanismWrapper::padding_size ( ) const

inline

Returns

the size of the padding in bytes (for encryption/decryption)

Definition at line 86 of file p11_mechanism.h.

{ return m_padding_size; }

set_ecdh_other_key()

void Botan::PKCS11::MechanismWrapper::set_ecdh_other_key ( const uint8_t other_key[], size_t other_key_len )

inline

Sets the public key of the other party for the ECDH mechanism parameters.

Parameters

other_key	key of the other party
other_key_len	size of the key of the other party in bytes

Definition at line 75 of file p11_mechanism.h.

                                                                                      {
         m_parameters->ecdh_params.pPublicData = const_cast<uint8_t*>(other_key);
         m_parameters->ecdh_params.ulPublicDataLen = static_cast<Ulong>(other_key_len);
      }

set_ecdh_salt()

void Botan::PKCS11::MechanismWrapper::set_ecdh_salt ( const uint8_t salt[], size_t salt_len )

inline

Sets the salt for the ECDH mechanism parameters.

Parameters

salt	the salt
salt_len	size of the salt in bytes

Definition at line 65 of file p11_mechanism.h.

                                                                       {
         m_parameters->ecdh_params.pSharedData = const_cast<uint8_t*>(salt);
         m_parameters->ecdh_params.ulSharedDataLen = static_cast<Ulong>(salt_len);
      }

---

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

• src/lib/prov/pkcs11/p11_mechanism.h
• src/lib/prov/pkcs11/p11_mechanism.cpp