Botan 3.9.0
Crypto and TLS for C&
mac.h
Go to the documentation of this file.
1/*
2* Base class for message authentiction codes
3* (C) 1999-2007 Jack Lloyd
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#ifndef BOTAN_MESSAGE_AUTH_CODE_BASE_H_
9#define BOTAN_MESSAGE_AUTH_CODE_BASE_H_
10
11#include <botan/buf_comp.h>
12#include <botan/sym_algo.h>
13#include <memory>
14#include <span>
15#include <string>
16
17namespace Botan {
18
19/**
20* This class represents Message Authentication Code (MAC) objects.
21*/
23 public SymmetricAlgorithm {
24 public:
25 /**
26 * Create an instance based on a name
27 * If provider is empty then best available is chosen.
28 * @param algo_spec algorithm name
29 * @param provider provider implementation to use
30 * @return a null pointer if the algo/provider combination cannot be found
31 */
32 static std::unique_ptr<MessageAuthenticationCode> create(std::string_view algo_spec,
33 std::string_view provider = "");
34
35 /*
36 * Create an instance based on a name
37 * If provider is empty then best available is chosen.
38 * @param algo_spec algorithm name
39 * @param provider provider implementation to use
40 * Throws a Lookup_Error if algo/provider combination cannot be found
41 */
42 static std::unique_ptr<MessageAuthenticationCode> create_or_throw(std::string_view algo_spec,
43 std::string_view provider = "");
44
45 /**
46 * @return list of available providers for this algorithm, empty if not available
47 */
48 static std::vector<std::string> providers(std::string_view algo_spec);
49
50 /**
51 * Prepare for processing a message under the specified nonce
52 *
53 * Most MACs neither require nor support a nonce; for these algorithms
54 * calling start() is optional and calling it with anything other than
55 * an empty string is an error. One MAC which *requires* a per-message
56 * nonce be specified is GMAC.
57 *
58 * Default implementation simply rejects all non-empty nonces
59 * since most hash/MAC algorithms do not support randomization
60 *
61 * @param nonce the message nonce bytes
62 */
63 void start(std::span<const uint8_t> nonce) { start_msg(nonce); }
64
65 /**
66 * Begin processing a message.
67 * @param nonce the per message nonce
68 * @param nonce_len length of nonce
69 */
70 void start(const uint8_t nonce[], size_t nonce_len) { start_msg({nonce, nonce_len}); }
71
72 /**
73 * Begin processing a message.
74 */
75 void start() { return start_msg({}); }
76
77 /**
78 * Verify a MAC.
79 * @param in the MAC to verify as a byte array
80 * @param length the length of param in
81 * @return true if the MAC is valid, false otherwise
82 */
83 bool verify_mac(const uint8_t in[], size_t length) { return verify_mac_result({in, length}); }
84
85 /**
86 * Verify a MAC.
87 * @param in the MAC to verify as a byte array
88 * @return true if the MAC is valid, false otherwise
89 */
90 bool verify_mac(std::span<const uint8_t> in) { return verify_mac_result(in); }
91
92 /**
93 * @return new object representing the same algorithm as *this
94 */
95 virtual std::unique_ptr<MessageAuthenticationCode> new_object() const = 0;
96
97 /**
98 * Get a new object representing the same algorithm as *this
99 */
100 MessageAuthenticationCode* clone() const { return this->new_object().release(); }
101
102 /**
103 * @return provider information about this implementation. Default is "base",
104 * might also return "sse2", "avx2", "openssl", or some other arbitrary string.
105 */
106 virtual std::string provider() const { return "base"; }
107
108 /**
109 * @return if a fresh key must be set for each message that is processed.
110 *
111 * This is required for certain polynomial-based MACs which are insecure
112 * if a key is ever reused for two different messages.
113 */
114 virtual bool fresh_key_required_per_message() const { return false; }
115
116 protected:
117 /**
118 * Prepare for processing a message under the specified nonce
119 *
120 * If the MAC does not support nonces, it should not override the default
121 * implementation.
122 */
123 virtual void start_msg(std::span<const uint8_t> nonce);
124
125 /**
126 * Verify the MACs final result
127 */
128 virtual bool verify_mac_result(std::span<const uint8_t> in);
129};
130
132
133} // namespace Botan
134
135#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
virtual bool verify_mac_result(std::span< const uint8_t > in)
Definition mac.cpp:166
bool verify_mac(std::span< const uint8_t > in)
Definition mac.h:90
virtual bool fresh_key_required_per_message() const
Definition mac.h:114
static std::unique_ptr< MessageAuthenticationCode > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition mac.cpp:148
virtual std::unique_ptr< MessageAuthenticationCode > new_object() const =0
static std::unique_ptr< MessageAuthenticationCode > create(std::string_view algo_spec, std::string_view provider="")
Definition mac.cpp:51
virtual std::string provider() const
Definition mac.h:106
virtual void start_msg(std::span< const uint8_t > nonce)
Definition mac.cpp:156
bool verify_mac(const uint8_t in[], size_t length)
Definition mac.h:83
static std::vector< std::string > providers(std::string_view algo_spec)
Definition mac.cpp:143
void start(std::span< const uint8_t > nonce)
Definition mac.h:63
MessageAuthenticationCode * clone() const
Definition mac.h:100
void start(const uint8_t nonce[], size_t nonce_len)
Definition mac.h:70
MessageAuthenticationCode MAC
Definition mac.h:131