Botan 3.14.1
Crypto and TLS for C&
Botan::AlgorithmSpec Class Referencefinal

#include <algorithm_spec.h>

Public Types

enum class  Syntax : uint8_t { Standard , CipherMode }

Public Member Functions

 AlgorithmSpec (std::string_view spec, Syntax syntax=Syntax::Standard)
const AlgorithmSpec & arg (size_t i) const
size_t arg_count () const
std::span< const AlgorithmSpec > args () const
std::string canonical_form () const
std::string_view head () const
std::optional< AlgorithmMatch > match (const AlgorithmPattern &pattern) const &
std::optional< AlgorithmMatch > match (const AlgorithmPattern &pattern) const &&=delete
bool matches (const AlgorithmPattern &pattern) const
std::string_view to_string () const
AlgorithmSpec with_head (std::string_view head) const

Detailed Description

A parsed algorithm specification such as "HMAC(SHA-256)" or "AES-128/GCM(12)"

Specifications have the form Head(arg,arg,...) where each argument is itself a specification. With Syntax::CipherMode the form "Cipher/Mode(args)/Pad" is also accepted at the top level and canonicalized to "Mode(Cipher,args,Pad)"; otherwise a slash is an ordinary character.

Factories should match against an AlgorithmPattern, which expresses the entire accepted form including defaults, rather than inspecting arguments positionally.

Definition at line 150 of file algorithm_spec.h.

Member Enumeration Documentation

◆ Syntax

enum class Botan::AlgorithmSpec::Syntax : uint8_t
strong
Enumerator
Standard 
CipherMode 

Definition at line 152 of file algorithm_spec.h.

152 : uint8_t {
153 Standard,
154 CipherMode,
155 };

Constructor & Destructor Documentation

◆ AlgorithmSpec()

Botan::AlgorithmSpec::AlgorithmSpec ( std::string_view spec,
Syntax syntax = Syntax::Standard )
explicit

Parse a specification

Exceptions
Invalid_Algorithm_Nameif the string is malformed

Definition at line 64 of file algorithm_spec.cpp.

64 {
65 if(spec.empty()) {
66 throw Invalid_Algorithm_Name(spec);
67 }
68
69 const bool mode_syntax = (syntax == Syntax::CipherMode);
70
71 // Fast path for a bare name such as "SHA-256", which is the common case
72 if(spec.find_first_of(mode_syntax ? "(),/" : "(),") == std::string_view::npos) {
73 m_text = std::string(spec);
74 m_head = std::string(spec);
75 return;
76 }
77
78 size_t pos = 0;
79 std::vector<AlgorithmSpec> parts;
80 parts.push_back(parse_name(spec, pos, 0, mode_syntax));
81
82 while(mode_syntax && pos < spec.size() && spec[pos] == '/') {
83 ++pos;
84 parts.push_back(parse_name(spec, pos, 0, mode_syntax));
85 }
86
87 if(pos != spec.size()) {
88 throw Invalid_Algorithm_Name(spec);
89 }
90
91 if(parts.size() == 1) {
92 m_head = std::move(parts[0].m_head);
93 m_args = std::move(parts[0].m_args);
94 } else {
95 // Cipher/Mode(args)/Pad becomes Mode(Cipher,args,Pad)
96 AlgorithmSpec& mode = parts[1];
97 m_head = std::move(mode.m_head);
98 m_args.push_back(std::move(parts[0]));
99 for(auto& mode_arg : mode.m_args) {
100 m_args.push_back(std::move(mode_arg));
101 }
102 for(size_t i = 2; i < parts.size(); ++i) {
103 m_args.push_back(std::move(parts[i]));
104 }
105 }
106
107 m_text = std::string(spec);
108}
AlgorithmSpec(std::string_view spec, Syntax syntax=Syntax::Standard)

References AlgorithmSpec(), and CipherMode.

Referenced by AlgorithmSpec(), arg(), match(), and with_head().

Member Function Documentation

◆ arg()

const AlgorithmSpec & Botan::AlgorithmSpec::arg ( size_t i) const
Returns
the ith argument
Exceptions
Invalid_Argumentif i is out of range

Definition at line 110 of file algorithm_spec.cpp.

110 {
111 if(i >= m_args.size()) {
112 throw Invalid_Argument(fmt("AlgorithmSpec::arg {} out of range for '{}'", i, m_text));
113 }
114 return m_args[i];
115}
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53

References AlgorithmSpec(), and Botan::fmt().

◆ arg_count()

size_t Botan::AlgorithmSpec::arg_count ( ) const
inline

Definition at line 173 of file algorithm_spec.h.

173{ return m_args.size(); }

Referenced by Botan::commoncrypto_opts_from_algo().

◆ args()

std::span< const AlgorithmSpec > Botan::AlgorithmSpec::args ( ) const
inline

Definition at line 175 of file algorithm_spec.h.

175{ return m_args; }

◆ canonical_form()

std::string Botan::AlgorithmSpec::canonical_form ( ) const
inline
Returns
the specification written as Head(arg,arg,...), which differs from to_string only for the cipher mode syntax

Definition at line 187 of file algorithm_spec.h.

187{ return text_with_head(m_head); }

Referenced by Botan::Cipher_Mode::create().

◆ head()

std::string_view Botan::AlgorithmSpec::head ( ) const
inline
Returns
the outermost algorithm name, eg "GCM" for "AES-128/GCM"

Definition at line 171 of file algorithm_spec.h.

171{ return m_head; }

Referenced by Botan::commoncrypto_opts_from_algo(), match(), Botan::parse_legacy_sig_options(), and with_head().

◆ match() [1/2]

std::optional< AlgorithmMatch > Botan::AlgorithmSpec::match ( const AlgorithmPattern & pattern) const &

Match this specification against a pattern

Returns
the bound variables, or nullopt if the pattern does not match. The result references this object and must not outlive it.

Definition at line 132 of file algorithm_spec.cpp.

132 {
133 // Factories try many patterns in turn, so reject on the head before
134 // setting up the (fairly large) match object
135 if(!pattern.any_head()) {
136 bool head_matches = false;
137 for(const auto alt : pattern.head_alternatives()) {
138 if(alt == m_head) {
139 head_matches = true;
140 break;
141 }
142 }
143 if(!head_matches) {
144 return std::nullopt;
145 }
146 }
147
148 AlgorithmMatch m(pattern, *this);
149
150 size_t idx = 0;
151 if(!match_args(pattern.elements(), idx, 0, m)) {
152 return std::nullopt;
153 }
154
155 return m;
156}

Referenced by Botan::TPM2::cipher_botan_to_tss2(), Botan::commoncrypto_opts_from_algo(), Botan::AEAD_Mode::create(), Botan::BlockCipher::create(), Botan::Cipher_Mode::create(), Botan::HashFunction::create(), Botan::KDF::create(), Botan::MessageAuthenticationCode::create(), Botan::PasswordHashFamily::create(), Botan::PBKDF::create(), Botan::StreamCipher::create(), Botan::PKCS11::MechanismWrapper::create_ecdsa_mechanism(), Botan::create_keccak_mb_engine(), Botan::create_sha2_32_mb_engine(), Botan::create_sha2_64_mb_engine(), Botan::PSS_Params::from_padding_name(), Botan::HSS_LMS_Params::HSS_LMS_Params(), matches(), Botan::parse_legacy_enc_options(), Botan::parse_legacy_sig_options(), Botan::TPM2::rsa_encryption_scheme_botan_to_tss2(), and Botan::TPM2::rsa_signature_scheme_botan_to_tss2().

◆ match() [2/2]

std::optional< AlgorithmMatch > Botan::AlgorithmSpec::match ( const AlgorithmPattern & pattern) const &&
delete

References AlgorithmSpec(), head(), matches(), and text.

◆ matches()

bool Botan::AlgorithmSpec::matches ( const AlgorithmPattern & pattern) const
inline
Returns
true if this specification matches the pattern

Definition at line 292 of file algorithm_spec.h.

292 {
293 return match(pattern).has_value();
294}
std::optional< AlgorithmMatch > match(const AlgorithmPattern &pattern) const &

References match().

Referenced by Botan::MessageAuthenticationCode::create(), Botan::PasswordHashFamily::create(), Botan::StreamCipher::create(), Botan::create_sha2_32_mb_engine(), Botan::create_sha2_64_mb_engine(), match(), Botan::parse_legacy_sig_options(), and Botan::TPM2::rsa_encryption_scheme_botan_to_tss2().

◆ to_string()

std::string_view Botan::AlgorithmSpec::to_string ( ) const
inline
Returns
the original text of the specification

Definition at line 166 of file algorithm_spec.h.

166{ return m_text; }

◆ with_head()

AlgorithmSpec Botan::AlgorithmSpec::with_head ( std::string_view head) const
inline
Returns
a copy of this specification with the head replaced, for folding deprecated aliases before matching

Definition at line 193 of file algorithm_spec.h.

193{ return AlgorithmSpec(text_with_head(head)); }
std::string_view head() const

References AlgorithmSpec(), and head().

Referenced by Botan::parse_legacy_sig_options().


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