Botan::PKCS11::MechanismWrapper Class Reference

#include <p11_mechanism.h>

Classes
union	MechanismParameters

Public Member Functions
Mechanism *	data () const
KeyDerivation	ecdh_kdf () 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 25 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 116 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_ecdh_mechanism(), create_ecdsa_mechanism(), create_rsa_crypt_mechanism(), and create_rsa_sign_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 277 of file p11_mechanism.cpp.

                                                                              {
   // note: when updating this map, update the documentation for `MechanismWrapper::create_ecdh_mechanism`
   static const std::map<std::string_view, KeyDerivation> EcdhHash = {{"Raw", KeyDerivation::Null},
                                                                      {"SHA-1", KeyDerivation::Sha1Kdf},
                                                                      {"SHA-224", KeyDerivation::Sha224Kdf},
                                                                      {"SHA-256", KeyDerivation::Sha256Kdf},
                                                                      {"SHA-384", KeyDerivation::Sha384Kdf},
                                                                      {"SHA-512", KeyDerivation::Sha512Kdf}};
 
   const 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));
   }
 
   // TODO(Botan4) remove this cofactor nonsense
   bool use_cofactor = false;
   std::string kdf_name;
   for(const auto& part : param_parts) {
      if(part == "Cofactor") {
         if(use_cofactor) {
            throw Invalid_Argument(fmt("PKCS #11 ECDH key derivation bad params {}", params));
         }
         use_cofactor = true;
      } else {
         if(!kdf_name.empty()) {
            throw Invalid_Argument(fmt("PKCS #11 ECDH key derivation bad params {}", params));
         }
         kdf_name = part;
      }
   }
 
   if(kdf_name.empty()) {
      throw Invalid_Argument(fmt("PKCS #11 ECDH key derivation bad params {}", params));
   }
 
   auto kdf = EcdhHash.find(kdf_name);
   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::PKCS11::Ecdh1CofactorDerive, Botan::PKCS11::Ecdh1Derive, Botan::fmt(), MechanismWrapper(), Botan::PKCS11::Null, CK_MECHANISM::pParameter, Botan::PKCS11::Sha1Kdf, Botan::PKCS11::Sha224Kdf, Botan::PKCS11::Sha256Kdf, Botan::PKCS11::Sha384Kdf, Botan::PKCS11::Sha512Kdf, 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

Hashes

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

Definition at line 250 of file p11_mechanism.cpp.

                                                                                       {
   // note: when updating this map, update the documentation for `MechanismWrapper::create_ecdsa_mechanism`
   static const std::map<std::string_view, MechanismType> EcdsaHash = {{"Raw", MechanismType::Ecdsa},
                                                                       {"SHA-1", MechanismType::EcdsaSha1},
                                                                       {"SHA-224", MechanismType::EcdsaSha224},
                                                                       {"SHA-256", MechanismType::EcdsaSha256},
                                                                       {"SHA-384", MechanismType::EcdsaSha384},
                                                                       {"SHA-512", MechanismType::EcdsaSha512}};
 
   const std::string hash_spec(hash_spec_view);
   auto mechanism = EcdsaHash.find(hash_spec);
   if(mechanism != EcdsaHash.end()) {
      return MechanismWrapper(mechanism->second);
   }
 
   const 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::PKCS11::Ecdsa, Botan::PKCS11::EcdsaSha1, Botan::PKCS11::EcdsaSha224, Botan::PKCS11::EcdsaSha256, Botan::PKCS11::EcdsaSha384, Botan::PKCS11::EcdsaSha512, 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 119 of file p11_mechanism.cpp.

                                                                                    {
   // note: when updating this map, update the documentation for `MechanismWrapper::create_rsa_crypt_mechanism`
   static const std::map<std::string_view, RSA_CryptMechanism> CryptMechanisms = {
      {"Raw", RSA_CryptMechanism(MechanismType::RsaX509, 0)},
      // TODO(Botan4) Remove this
      {"EME-PKCS1-v1_5", RSA_CryptMechanism(MechanismType::RsaPkcs, 11)},
      {"PKCS1v15", RSA_CryptMechanism(MechanismType::RsaPkcs, 11)},
      {"OAEP(SHA-1)", RSA_CryptMechanism(MechanismType::RsaPkcsOaep, 2 + 2 * 20, MechanismType::Sha1, MGF::Mgf1Sha1)},
      {"OAEP(SHA-224)",
       RSA_CryptMechanism(MechanismType::RsaPkcsOaep, 2 + 2 * 28, MechanismType::Sha224, MGF::Mgf1Sha224)},
      {"OAEP(SHA-256)",
       RSA_CryptMechanism(MechanismType::RsaPkcsOaep, 2 + 2 * 32, MechanismType::Sha256, MGF::Mgf1Sha256)},
      {"OAEP(SHA-384)",
       RSA_CryptMechanism(MechanismType::RsaPkcsOaep, 2 + 2 * 48, MechanismType::Sha384, MGF::Mgf1Sha384)},
      {"OAEP(SHA-512)",
       RSA_CryptMechanism(MechanismType::RsaPkcsOaep, 2 + 2 * 64, MechanismType::Sha512, MGF::Mgf1Sha512)}};
 
   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(fmt("PKCS#11 RSA encrypt/decrypt does not support padding with '{}'", padding));
   }
   const 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, Botan::fmt(), MechanismWrapper(), Botan::PKCS11::Mgf1Sha1, Botan::PKCS11::Mgf1Sha224, Botan::PKCS11::Mgf1Sha256, Botan::PKCS11::Mgf1Sha384, Botan::PKCS11::Mgf1Sha512, CK_MECHANISM::pParameter, Botan::PKCS11::RsaPkcs, Botan::PKCS11::RsaPkcsOaep, Botan::PKCS11::RsaX509, Botan::PKCS11::Sha1, Botan::PKCS11::Sha224, Botan::PKCS11::Sha256, Botan::PKCS11::Sha384, Botan::PKCS11::Sha512, 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 158 of file p11_mechanism.cpp.

                                                                                   {
   // note: when updating this map, update the documentation for `MechanismWrapper::create_rsa_sign_mechanism`
   static const std::map<std::string_view, RSA_SignMechanism> SignMechanisms = {
      {"Raw", RSA_SignMechanism(MechanismType::RsaX509)},
 
      // X9.31
      {"X9.31(Raw)", RSA_SignMechanism(MechanismType::RsaX931)},
      {"X9.31(SHA-1)", RSA_SignMechanism(MechanismType::Sha1RsaX931)},
 
      // RSASSA PKCS#1 v1.5
      {"PKCS1v15(SHA-1)", RSA_SignMechanism(MechanismType::Sha1RsaPkcs)},
      {"PKCS1v15(SHA-224)", RSA_SignMechanism(MechanismType::Sha224RsaPkcs)},
      {"PKCS1v15(SHA-256)", RSA_SignMechanism(MechanismType::Sha256RsaPkcs)},
      {"PKCS1v15(SHA-384)", RSA_SignMechanism(MechanismType::Sha384RsaPkcs)},
      {"PKCS1v15(SHA-512)", RSA_SignMechanism(MechanismType::Sha512RsaPkcs)},
 
      // PSS PKCS#1 v2.0
      {"PSS(Raw)", RSA_SignMechanism(MechanismType::RsaPkcsPss)},
 
      {"PSS(SHA-1)", RSA_SignMechanism(MechanismType::Sha1RsaPkcsPss)},
      {"PSS(SHA-1,MGF1,20)", RSA_SignMechanism(MechanismType::Sha1RsaPkcsPss)},
 
      {"PSS(SHA-224)", RSA_SignMechanism(MechanismType::Sha224RsaPkcsPss)},
      {"PSS(SHA-224,MGF1,28)", RSA_SignMechanism(MechanismType::Sha224RsaPkcsPss)},
 
      {"PSS(SHA-256)", RSA_SignMechanism(MechanismType::Sha256RsaPkcsPss)},
      {"PSS(SHA-256,MGF1,32)", RSA_SignMechanism(MechanismType::Sha256RsaPkcsPss)},
 
      {"PSS(SHA-384)", RSA_SignMechanism(MechanismType::Sha384RsaPkcsPss)},
      {"PSS(SHA-384,MGF1,48)", RSA_SignMechanism(MechanismType::Sha384RsaPkcsPss)},
 
      {"PSS(SHA-512)", RSA_SignMechanism(MechanismType::Sha512RsaPkcsPss)},
      {"PSS(SHA-512,MGF1,64)", RSA_SignMechanism(MechanismType::Sha512RsaPkcsPss)},
 
      // ISO 9796 - this is the obsolete and insecure DS1 scheme, not the PSS-based DS2/DS3
      // TODO(Botan4) remove this
      {"ISO9796", RSA_SignMechanism(MechanismType::Rsa9796)},
 
      // Deprecated aliases
      // TODO(Botan4) remove these
      {"EMSA2(Raw)", RSA_SignMechanism(MechanismType::RsaX931)},
      {"EMSA2(SHA-1)", RSA_SignMechanism(MechanismType::Sha1RsaX931)},
 
      {"EMSA3(Raw)", RSA_SignMechanism(MechanismType::RsaPkcs)},
      {"EMSA3(SHA-1)", RSA_SignMechanism(MechanismType::Sha1RsaPkcs)},
      {"EMSA3(SHA-224)", RSA_SignMechanism(MechanismType::Sha224RsaPkcs)},
      {"EMSA3(SHA-256)", RSA_SignMechanism(MechanismType::Sha256RsaPkcs)},
      {"EMSA3(SHA-384)", RSA_SignMechanism(MechanismType::Sha384RsaPkcs)},
      {"EMSA3(SHA-512)", RSA_SignMechanism(MechanismType::Sha512RsaPkcs)},
 
      {"EMSA_PKCS1(SHA-1)", RSA_SignMechanism(MechanismType::Sha1RsaPkcs)},
      {"EMSA_PKCS1(SHA-224)", RSA_SignMechanism(MechanismType::Sha224RsaPkcs)},
      {"EMSA_PKCS1(SHA-256)", RSA_SignMechanism(MechanismType::Sha256RsaPkcs)},
      {"EMSA_PKCS1(SHA-384)", RSA_SignMechanism(MechanismType::Sha384RsaPkcs)},
      {"EMSA_PKCS1(SHA-512)", RSA_SignMechanism(MechanismType::Sha512RsaPkcs)},
 
      {"EMSA4(Raw)", RSA_SignMechanism(MechanismType::RsaPkcsPss)},
      {"EMSA4(SHA-1)", RSA_SignMechanism(MechanismType::Sha1RsaPkcsPss)},
      {"EMSA4(SHA-224)", RSA_SignMechanism(MechanismType::Sha224RsaPkcsPss)},
 
      {"EMSA4(SHA-256)", RSA_SignMechanism(MechanismType::Sha256RsaPkcsPss)},
      {"EMSA4(SHA-256,MGF1,32)", RSA_SignMechanism(MechanismType::Sha256RsaPkcsPss)},
      {"PSSR(SHA-256,MGF1,32)", RSA_SignMechanism(MechanismType::Sha256RsaPkcsPss)},
 
      {"EMSA4(SHA-384)", RSA_SignMechanism(MechanismType::Sha384RsaPkcsPss)},
      {"EMSA4(SHA-384,MGF1,48)", RSA_SignMechanism(MechanismType::Sha384RsaPkcsPss)},
      {"PSSR(SHA-384,MGF1,48)", RSA_SignMechanism(MechanismType::Sha384RsaPkcsPss)},
 
      {"EMSA4(SHA-512)", RSA_SignMechanism(MechanismType::Sha512RsaPkcsPss)},
      {"EMSA4(SHA-512,MGF1,64)", RSA_SignMechanism(MechanismType::Sha512RsaPkcsPss)},
      {"PSSR(SHA-512,MGF1,64)", RSA_SignMechanism(MechanismType::Sha512RsaPkcsPss)},
   };
 
   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(fmt("PKCS#11 RSA sign/verify does not support padding with '{}'", padding));
   }
   const RSA_SignMechanism mechanism_info = mechanism_info_it->second;
 
   MechanismWrapper mech(mechanism_info.type());
   if(PssOptions().contains(mechanism_info.type())) {
      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 = checked_ulong_cast(mechanism_info.salt_size());
      mech.m_mechanism.pParameter = mech.m_parameters.get();
      mech.m_mechanism.ulParameterLen = sizeof(RsaPkcsPssParams);
   }
   return mech;
}

References Botan::PKCS11::checked_ulong_cast(), Botan::fmt(), MechanismWrapper(), CK_MECHANISM::pParameter, Botan::PKCS11::Rsa9796, Botan::PKCS11::RsaPkcs, Botan::PKCS11::RsaPkcsPss, Botan::PKCS11::RsaX509, Botan::PKCS11::RsaX931, Botan::PKCS11::Sha1RsaPkcs, Botan::PKCS11::Sha1RsaPkcsPss, Botan::PKCS11::Sha1RsaX931, Botan::PKCS11::Sha224RsaPkcs, Botan::PKCS11::Sha224RsaPkcsPss, Botan::PKCS11::Sha256RsaPkcs, Botan::PKCS11::Sha256RsaPkcsPss, Botan::PKCS11::Sha384RsaPkcs, Botan::PKCS11::Sha384RsaPkcsPss, Botan::PKCS11::Sha512RsaPkcs, Botan::PKCS11::Sha512RsaPkcsPss, 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 80 of file p11_mechanism.h.

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

ecdh_kdf()

KeyDerivation Botan::PKCS11::MechanismWrapper::ecdh_kdf ( ) const

inline

Returns

the KDF type for an ECDH mechanism

Definition at line 88 of file p11_mechanism.h.

{ return static_cast<KeyDerivation>(m_parameters->ecdh_params.kdf); }

mechanism_type()

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

inline

Definition at line 82 of file p11_mechanism.h.

{ return static_cast<MechanismType>(m_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 85 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 74 of file p11_mechanism.h.

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

References Botan::PKCS11::checked_ulong_cast().

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 64 of file p11_mechanism.h.

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

References Botan::PKCS11::checked_ulong_cast().

---

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