tls_signature_scheme.cpp

Go to the documentation of this file.

/*
* (C) 2022,2023 Jack Lloyd
* (C) 2022 René Meusel, Hannes Rantzsch - neXenio GmbH
*
* Botan is released under the Simplified BSD License (see license.txt)
*/
 
#include <botan/assert.h>
#include <botan/tls_signature_scheme.h>
 
#include <botan/hex.h>
#include <botan/pk_keys.h>
#include <botan/pss_params.h>
#include <botan/tls_version.h>
#include <botan/internal/fmt.h>
#include <botan/internal/loadstor.h>
 
namespace Botan::TLS {
 
const std::vector<Signature_Scheme>& Signature_Scheme::all_available_schemes() {
   /*
   * This is ordered in some approximate order of preference
   */
   static const std::vector<Signature_Scheme> all_schemes = {
 
      // EdDSA 25519 is currently not supported as a signature scheme for certificates
      // certificate authentication.
      // See: https://github.com/randombit/botan/pull/2958#discussion_r851294715
      //
      // #if defined(BOTAN_HAS_ED25519)
      //       EDDSA_25519,
      // #endif
 
      ECDSA_SECP384R1_TLS13_SHA384,
      ECDSA_SECP521R1_TLS13_SHA512,
      ECDSA_SECP256R1_TLS13_SHA256,
 
      RSA_PSS_SHA384,
      RSA_PSS_SHA256,
      RSA_PSS_SHA512,
 
      ECDSA_BRAINPOOL384R1_TLS13_SHA384,
      ECDSA_BRAINPOOL256R1_TLS13_SHA256,
      ECDSA_BRAINPOOL512R1_TLS13_SHA512,
 
      RSA_PKCS1_SHA384,
      RSA_PKCS1_SHA512,
      RSA_PKCS1_SHA256,
   };
 
   return all_schemes;
}
 
Signature_Scheme Signature_Scheme::from_string(std::string_view str) {
   if(str == "RSA_PKCS1_SHA1") {
      return RSA_PKCS1_SHA1;
   }
   if(str == "RSA_PKCS1_SHA256") {
      return RSA_PKCS1_SHA256;
   }
   if(str == "RSA_PKCS1_SHA384") {
      return RSA_PKCS1_SHA384;
   }
   if(str == "RSA_PKCS1_SHA512") {
      return RSA_PKCS1_SHA512;
   }
 
   if(str == "ECDSA_SHA1") {
      return ECDSA_SHA1;
   }
   if(str == "ECDSA_SHA256" || str == "ECDSA_SECP256R1_TLS13_SHA256") {
      return ECDSA_SECP256R1_TLS13_SHA256;
   }
   if(str == "ECDSA_SHA384" || str == "ECDSA_SECP384R1_TLS13_SHA384") {
      return ECDSA_SECP384R1_TLS13_SHA384;
   }
   if(str == "ECDSA_SHA512" || str == "ECDSA_SECP521R1_TLS13_SHA512") {
      return ECDSA_SECP521R1_TLS13_SHA512;
   }
 
   if(str == "RSA_PSS_SHA256") {
      return RSA_PSS_SHA256;
   }
   if(str == "RSA_PSS_SHA384") {
      return RSA_PSS_SHA384;
   }
   if(str == "RSA_PSS_SHA512") {
      return RSA_PSS_SHA512;
   }
 
   if(str == "ECDSA_BRAINPOOL256R1_TLS13_SHA256") {
      return ECDSA_BRAINPOOL256R1_TLS13_SHA256;
   }
   if(str == "ECDSA_BRAINPOOL384R1_TLS13_SHA384") {
      return ECDSA_BRAINPOOL384R1_TLS13_SHA384;
   }
   if(str == "ECDSA_BRAINPOOL512R1_TLS13_SHA512") {
      return ECDSA_BRAINPOOL512R1_TLS13_SHA512;
   }
 
   // Parse signature schemes passed as hexadecimal code points (e.g. "0x081A")
   if(str.size() == 6 && str.starts_with("0x")) {
      try {
         std::array<uint8_t, 2> wire_code{};
         Botan::hex_decode(wire_code, str.substr(2), false /* no white space */);
         return Signature_Scheme(load_be(wire_code));
      } catch(const Invalid_Argument&) {
         // pass, will throw below
      }
   }
 
   throw Invalid_Argument(fmt("Unknown TLS signature scheme '{}'", str));
}
 
Signature_Scheme::Signature_Scheme() : m_code(NONE) {}
 
Signature_Scheme::Signature_Scheme(uint16_t wire_code) : Signature_Scheme(Signature_Scheme::Code(wire_code)) {}
 
Signature_Scheme::Signature_Scheme(Signature_Scheme::Code wire_code) : m_code(wire_code) {}
 
bool Signature_Scheme::is_available() const noexcept {
   switch(m_code) {
      case RSA_PSS_SHA384:
      case RSA_PSS_SHA256:
      case RSA_PSS_SHA512:
      case RSA_PKCS1_SHA384:
      case RSA_PKCS1_SHA512:
      case RSA_PKCS1_SHA256:
      case ECDSA_BRAINPOOL384R1_TLS13_SHA384:
      case ECDSA_BRAINPOOL256R1_TLS13_SHA256:
      case ECDSA_BRAINPOOL512R1_TLS13_SHA512:
      case ECDSA_SECP384R1_TLS13_SHA384:
      case ECDSA_SECP521R1_TLS13_SHA512:
      case ECDSA_SECP256R1_TLS13_SHA256:
         return true;
      default:
         return false;
   }
}
 
bool Signature_Scheme::is_set() const noexcept {
   return m_code != NONE;
}
 
std::string Signature_Scheme::to_string() const {
   switch(m_code) {
      case RSA_PKCS1_SHA1:
         return "RSA_PKCS1_SHA1";
      case RSA_PKCS1_SHA256:
         return "RSA_PKCS1_SHA256";
      case RSA_PKCS1_SHA384:
         return "RSA_PKCS1_SHA384";
      case RSA_PKCS1_SHA512:
         return "RSA_PKCS1_SHA512";
 
      case ECDSA_SHA1:
         return "ECDSA_SHA1";
      case ECDSA_SECP256R1_TLS13_SHA256:
         return "ECDSA_SHA256";
      case ECDSA_SECP384R1_TLS13_SHA384:
         return "ECDSA_SHA384";
      case ECDSA_SECP521R1_TLS13_SHA512:
         return "ECDSA_SHA512";
 
      case ECDSA_BRAINPOOL256R1_TLS13_SHA256:
         return "ECDSA_BRAINPOOL256R1_TLS13_SHA256";
      case ECDSA_BRAINPOOL384R1_TLS13_SHA384:
         return "ECDSA_BRAINPOOL384R1_TLS13_SHA384";
      case ECDSA_BRAINPOOL512R1_TLS13_SHA512:
         return "ECDSA_BRAINPOOL512R1_TLS13_SHA512";
 
      case RSA_PSS_SHA256:
         return "RSA_PSS_SHA256";
      case RSA_PSS_SHA384:
         return "RSA_PSS_SHA384";
      case RSA_PSS_SHA512:
         return "RSA_PSS_SHA512";
 
      case EDDSA_25519:
         return "EDDSA_25519";
      case EDDSA_448:
         return "EDDSA_448";
 
      default:
         return "Unknown signature scheme: " + std::to_string(m_code);
   }
}
 
std::string Signature_Scheme::hash_function_name() const {
   switch(m_code) {
      case RSA_PKCS1_SHA1:
      case ECDSA_SHA1:
         return "SHA-1";
 
      case ECDSA_SECP256R1_TLS13_SHA256:
      case RSA_PKCS1_SHA256:
      case RSA_PSS_SHA256:
      case ECDSA_BRAINPOOL256R1_TLS13_SHA256:
         return "SHA-256";
 
      case ECDSA_SECP384R1_TLS13_SHA384:
      case RSA_PKCS1_SHA384:
      case RSA_PSS_SHA384:
      case ECDSA_BRAINPOOL384R1_TLS13_SHA384:
         return "SHA-384";
 
      case ECDSA_SECP521R1_TLS13_SHA512:
      case RSA_PKCS1_SHA512:
      case RSA_PSS_SHA512:
      case ECDSA_BRAINPOOL512R1_TLS13_SHA512:
         return "SHA-512";
 
      case EDDSA_25519:
      case EDDSA_448:
         return "Pure";
 
      default:
         return "Unknown hash function";
   }
}
 
std::string Signature_Scheme::padding_string() const {
   switch(m_code) {
      case RSA_PKCS1_SHA1:
         return "PKCS1v15(SHA-1)";
      case RSA_PKCS1_SHA256:
         return "PKCS1v15(SHA-256)";
      case RSA_PKCS1_SHA384:
         return "PKCS1v15(SHA-384)";
      case RSA_PKCS1_SHA512:
         return "PKCS1v15(SHA-512)";
 
      case ECDSA_SHA1:
         return "SHA-1";
      case ECDSA_SECP256R1_TLS13_SHA256:
      case ECDSA_BRAINPOOL256R1_TLS13_SHA256:
         return "SHA-256";
      case ECDSA_SECP384R1_TLS13_SHA384:
      case ECDSA_BRAINPOOL384R1_TLS13_SHA384:
         return "SHA-384";
      case ECDSA_SECP521R1_TLS13_SHA512:
      case ECDSA_BRAINPOOL512R1_TLS13_SHA512:
         return "SHA-512";
 
      case RSA_PSS_SHA256:
         return "PSS(SHA-256,MGF1,32)";
      case RSA_PSS_SHA384:
         return "PSS(SHA-384,MGF1,48)";
      case RSA_PSS_SHA512:
         return "PSS(SHA-512,MGF1,64)";
 
      case EDDSA_25519:
      case EDDSA_448:
         return "Pure";
 
      default:
         return "Unknown padding";
   }
}
 
std::string Signature_Scheme::algorithm_name() const {
   switch(m_code) {
      case RSA_PKCS1_SHA1:
      case RSA_PKCS1_SHA256:
      case RSA_PKCS1_SHA384:
      case RSA_PKCS1_SHA512:
      case RSA_PSS_SHA256:
      case RSA_PSS_SHA384:
      case RSA_PSS_SHA512:
         return "RSA";
 
      case ECDSA_SHA1:
      case ECDSA_SECP256R1_TLS13_SHA256:
      case ECDSA_SECP384R1_TLS13_SHA384:
      case ECDSA_SECP521R1_TLS13_SHA512:
      case ECDSA_BRAINPOOL256R1_TLS13_SHA256:
      case ECDSA_BRAINPOOL384R1_TLS13_SHA384:
      case ECDSA_BRAINPOOL512R1_TLS13_SHA512:
         return "ECDSA";
 
      case EDDSA_25519:
         return "Ed25519";
 
      case EDDSA_448:
         return "Ed448";
 
      default:
         return "Unknown algorithm";
   }
}
 
AlgorithmIdentifier Signature_Scheme::key_algorithm_identifier() const {
   const auto der_encode_oid = [](const std::string_view oid_name) {
      try {
         if(auto oid = OID::from_name(oid_name)) {
            return oid->BER_encode();
         }
      } catch(...) {}
      BOTAN_ASSERT_UNREACHABLE();
   };
 
   switch(m_code) {
      // case ECDSA_SHA1:  not defined
      case ECDSA_SECP256R1_TLS13_SHA256:
         return {"ECDSA", der_encode_oid("secp256r1")};
      case ECDSA_SECP384R1_TLS13_SHA384:
         return {"ECDSA", der_encode_oid("secp384r1")};
      case ECDSA_SECP521R1_TLS13_SHA512:
         return {"ECDSA", der_encode_oid("secp521r1")};
 
      case ECDSA_BRAINPOOL256R1_TLS13_SHA256:
         return {"ECDSA", der_encode_oid("brainpool256r1")};
      case ECDSA_BRAINPOOL384R1_TLS13_SHA384:
         return {"ECDSA", der_encode_oid("brainpool384r1")};
      case ECDSA_BRAINPOOL512R1_TLS13_SHA512:
         return {"ECDSA", der_encode_oid("brainpool512r1")};
 
      case EDDSA_25519:
         return {"Ed25519", AlgorithmIdentifier::USE_EMPTY_PARAM};
      case EDDSA_448:
         return {"Ed448", AlgorithmIdentifier::USE_EMPTY_PARAM};
 
      case RSA_PKCS1_SHA1:
      case RSA_PKCS1_SHA256:
      case RSA_PKCS1_SHA384:
      case RSA_PKCS1_SHA512:
      case RSA_PSS_SHA256:
      case RSA_PSS_SHA384:
      case RSA_PSS_SHA512:
         return {"RSA", AlgorithmIdentifier::USE_NULL_PARAM};
 
      default:
         return AlgorithmIdentifier();
   }
}
 
AlgorithmIdentifier Signature_Scheme::algorithm_identifier() const {
   switch(m_code) {
      case RSA_PKCS1_SHA1:
         return AlgorithmIdentifier(OID::from_string("RSA/PKCS1v15(SHA-1)"), AlgorithmIdentifier::USE_NULL_PARAM);
      case RSA_PKCS1_SHA256:
         return AlgorithmIdentifier(OID::from_string("RSA/PKCS1v15(SHA-256)"), AlgorithmIdentifier::USE_NULL_PARAM);
      case RSA_PKCS1_SHA384:
         return AlgorithmIdentifier(OID::from_string("RSA/PKCS1v15(SHA-384)"), AlgorithmIdentifier::USE_NULL_PARAM);
      case RSA_PKCS1_SHA512:
         return AlgorithmIdentifier(OID::from_string("RSA/PKCS1v15(SHA-512)"), AlgorithmIdentifier::USE_NULL_PARAM);
 
      case ECDSA_SHA1:
         return AlgorithmIdentifier(OID::from_string("ECDSA/SHA-1"), AlgorithmIdentifier::USE_EMPTY_PARAM);
      case ECDSA_SECP256R1_TLS13_SHA256:
      case ECDSA_BRAINPOOL256R1_TLS13_SHA256:
         return AlgorithmIdentifier(OID::from_string("ECDSA/SHA-256"), AlgorithmIdentifier::USE_EMPTY_PARAM);
      case ECDSA_SECP384R1_TLS13_SHA384:
      case ECDSA_BRAINPOOL384R1_TLS13_SHA384:
         return AlgorithmIdentifier(OID::from_string("ECDSA/SHA-384"), AlgorithmIdentifier::USE_EMPTY_PARAM);
      case ECDSA_SECP521R1_TLS13_SHA512:
      case ECDSA_BRAINPOOL512R1_TLS13_SHA512:
         return AlgorithmIdentifier(OID::from_string("ECDSA/SHA-512"), AlgorithmIdentifier::USE_EMPTY_PARAM);
 
      case RSA_PSS_SHA256:
         return AlgorithmIdentifier(OID::from_string("RSA/PSS"), PSS_Params("SHA-256", 32).serialize());
      case RSA_PSS_SHA384:
         return AlgorithmIdentifier(OID::from_string("RSA/PSS"), PSS_Params("SHA-384", 48).serialize());
      case RSA_PSS_SHA512:
         return AlgorithmIdentifier(OID::from_string("RSA/PSS"), PSS_Params("SHA-512", 64).serialize());
 
      default:
         // Note that Ed25519 and Ed448 end up here
         return AlgorithmIdentifier();
   }
}
 
std::optional<Signature_Format> Signature_Scheme::format() const noexcept {
   switch(m_code) {
      case RSA_PKCS1_SHA1:
      case RSA_PKCS1_SHA256:
      case RSA_PKCS1_SHA384:
      case RSA_PKCS1_SHA512:
      case RSA_PSS_SHA256:
      case RSA_PSS_SHA384:
      case RSA_PSS_SHA512:
      case EDDSA_25519:
      case EDDSA_448:
         return Signature_Format::Standard;
 
      case ECDSA_SHA1:
      case ECDSA_SECP256R1_TLS13_SHA256:
      case ECDSA_SECP384R1_TLS13_SHA384:
      case ECDSA_SECP521R1_TLS13_SHA512:
      case ECDSA_BRAINPOOL256R1_TLS13_SHA256:
      case ECDSA_BRAINPOOL384R1_TLS13_SHA384:
      case ECDSA_BRAINPOOL512R1_TLS13_SHA512:
         return Signature_Format::DerSequence;
 
      default:
         return std::nullopt;
   }
}
 
bool Signature_Scheme::is_compatible_with(const Protocol_Version& protocol_version) const noexcept {
   // RFC 8446 4.4.3:
   //   The SHA-1 algorithm MUST NOT be used in any signatures of
   //   CertificateVerify messages.
   //
   // Note that Botan enforces that for TLS 1.2 as well.
   if(m_code == RSA_PKCS1_SHA1 || m_code == ECDSA_SHA1) {
      return false;
   }
 
   // RFC 8446 4.4.3:
   //   RSA signatures MUST use an RSASSA-PSS algorithm, regardless of whether
   //   RSASSA-PKCS1-v1_5 algorithms appear in "signature_algorithms".
   //
   // Note that this is enforced for TLS 1.3 and above only.
   if(!protocol_version.is_pre_tls_13() && (m_code == RSA_PKCS1_SHA1 || m_code == RSA_PKCS1_SHA256 ||
                                            m_code == RSA_PKCS1_SHA384 || m_code == RSA_PKCS1_SHA512)) {
      return false;
   }
 
   return true;
}
 
bool Signature_Scheme::is_suitable_for(const Private_Key& private_key) const {
   if(algorithm_name() != private_key.algo_name()) {
      return false;
   }
 
   // The ECDSA private key length must match the utilized hash output length.
   const auto keylen = private_key.key_length();
   if(keylen <= 250) {
      return false;
   }
 
   if(algorithm_name() == "ECDSA") {
      if(hash_function_name() == "SHA-256" && !(keylen >= 250 && keylen <= 350)) {
         return false;
      }
 
      if(hash_function_name() == "SHA-384" && !(keylen >= 350 && keylen <= 450)) {
         return false;
      }
 
      if(hash_function_name() == "SHA-512" && !(keylen >= 450 && keylen <= 550)) {
         return false;
      }
   }
 
   return true;
}
 
std::vector<AlgorithmIdentifier> to_algorithm_identifiers(const std::vector<Signature_Scheme>& schemes) {
   std::vector<AlgorithmIdentifier> result;
   result.reserve(schemes.size());
   for(const auto& scheme : schemes) {
      result.push_back(scheme.algorithm_identifier());
   }
   return result;
}
 
}  // namespace Botan::TLS