Coverage Report

Created: 2023-06-07 07:00

/src/botan/build/include/botan/mac.h
Line
Count
Source (jump to first uncovered line)
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
17
namespace Botan {
18
19
/**
20
* This class represents Message Authentication Code (MAC) objects.
21
*/
22
class BOTAN_PUBLIC_API(2, 0) MessageAuthenticationCode : public Buffered_Computation,
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
1
      virtual ~MessageAuthenticationCode() = 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
0
      void start(std::span<const uint8_t> nonce) { start_msg(nonce.data(), nonce.size()); }
66
67
      /**
68
      * Begin processing a message.
69
      * @param nonce the per message nonce
70
      * @param nonce_len length of nonce
71
      */
72
0
      void start(const uint8_t nonce[], size_t nonce_len) { start_msg(nonce, nonce_len); }
73
74
      /**
75
      * Begin processing a message.
76
      */
77
0
      void start() { return start_msg(nullptr, 0); }
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
0
      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
0
      bool verify_mac(std::span<const uint8_t> in) { return verify_mac_result(in.data(), in.size()); }
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
0
      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
0
      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
0
      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(const uint8_t nonce[], size_t nonce_len);
126
127
      /**
128
      * Verify the MACs final result
129
      */
130
      virtual bool verify_mac_result(const uint8_t in[], size_t length);
131
};
132
133
typedef MessageAuthenticationCode MAC;
134
135
}  // namespace Botan
136
137
#endif