Botan 3.3.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 ~MessageAuthenticationCode() override = default;
51
52 /**
53 * Prepare for processing a message under the specified nonce
54 *
55 * Most MACs neither require nor support a nonce; for these algorithms
56 * calling `start_msg` is optional and calling it with anything other than
57 * an empty string is an error. One MAC which *requires* a per-message
58 * nonce be specified is GMAC.
59 *
60 * Default implementation simply rejects all non-empty nonces
61 * since most hash/MAC algorithms do not support randomization
62 *
63 * @param nonce the message nonce bytes
64 */
65 void start(std::span<const uint8_t> nonce) { start_msg(nonce); }
66
67 /**
68 * Begin processing a message.
69 * @param nonce the per message nonce
70 * @param nonce_len length of nonce
71 */
72 void start(const uint8_t nonce[], size_t nonce_len) { start_msg({nonce, nonce_len}); }
73
74 /**
75 * Begin processing a message.
76 */
77 void start() { return start_msg({}); }
78
79 /**
80 * Verify a MAC.
81 * @param in the MAC to verify as a byte array
82 * @param length the length of param in
83 * @return true if the MAC is valid, false otherwise
84 */
85 bool verify_mac(const uint8_t in[], size_t length) { return verify_mac_result({in, length}); }
86
87 /**
88 * Verify a MAC.
89 * @param in the MAC to verify as a byte array
90 * @return true if the MAC is valid, false otherwise
91 */
92 bool verify_mac(std::span<const uint8_t> in) { return verify_mac_result(in); }
93
94 /**
95 * @return new object representing the same algorithm as *this
96 */
97 virtual std::unique_ptr<MessageAuthenticationCode> new_object() const = 0;
98
99 /**
100 * Get a new object representing the same algorithm as *this
101 */
102 MessageAuthenticationCode* clone() const { return this->new_object().release(); }
103
104 /**
105 * @return provider information about this implementation. Default is "base",
106 * might also return "sse2", "avx2", "openssl", or some other arbitrary string.
107 */
108 virtual std::string provider() const { return "base"; }
109
110 /**
111 * @return if a fresh key must be set for each message that is processed.
112 *
113 * This is required for certain polynomial-based MACs which are insecure
114 * if a key is ever reused for two different messages.
115 */
116 virtual bool fresh_key_required_per_message() const { return false; }
117
118 protected:
119 /**
120 * Prepare for processing a message under the specified nonce
121 *
122 * If the MAC does not support nonces, it should not override the default
123 * implementation.
124 */
125 virtual void start_msg(std::span<const uint8_t> nonce);
126
127 /**
128 * Verify the MACs final result
129 */
130 virtual bool verify_mac_result(std::span<const uint8_t> in);
131};
132
134
135} // namespace Botan
136
137#endif
~MessageAuthenticationCode() override=default
bool verify_mac(std::span< const uint8_t > in)
Definition mac.h:92
virtual bool fresh_key_required_per_message() const
Definition mac.h:116
virtual std::unique_ptr< MessageAuthenticationCode > new_object() const =0
virtual std::string provider() const
Definition mac.h:108
bool verify_mac(const uint8_t in[], size_t length)
Definition mac.h:85
void start(std::span< const uint8_t > nonce)
Definition mac.h:65
MessageAuthenticationCode * clone() const
Definition mac.h:102
void start(const uint8_t nonce[], size_t nonce_len)
Definition mac.h:72
#define BOTAN_PUBLIC_API(maj, min)
Definition compiler.h:31
MessageAuthenticationCode MAC
Definition mac.h:133