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 <string>
14 #include <memory>
15 
16 namespace Botan {
17 
18 /**
19 * This class represents Message Authentication Code (MAC) objects.
20 */
21 class BOTAN_PUBLIC_API(2,0) MessageAuthenticationCode : public Buffered_Computation,
22                                             public SymmetricAlgorithm
23    {
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>
33          create(const std::string& algo_spec,
34                 const std::string& provider = "");
35 
36       /*
37       * Create an instance based on a name
38       * If provider is empty then best available is chosen.
39       * @param algo_spec algorithm name
40       * @param provider provider implementation to use
41       * Throws a Lookup_Error if algo/provider combination cannot be found
42       */
43       static std::unique_ptr<MessageAuthenticationCode>
44          create_or_throw(const std::string& algo_spec,
45                          const std::string& provider = "");
46 
47       /**
48       * @return list of available providers for this algorithm, empty if not available
49       */
50       static std::vector<std::string> providers(const std::string& algo_spec);
51 
52       virtual ~MessageAuthenticationCode() = default;
53 
54       /**
55       * Prepare for processing a message under the specified nonce
56       *
57       * Most MACs neither require nor support a nonce; for these algorithms
58       * calling `start_msg` is optional and calling it with anything other than
59       * an empty string is an error. One MAC which *requires* a per-message
60       * nonce be specified is GMAC.
61       *
62       * @param nonce the message nonce bytes
63       * @param nonce_len the size of len in bytes
64       * Default implementation simply rejects all non-empty nonces
65       * since most hash/MAC algorithms do not support randomization
66       */
67       virtual void start_msg(const uint8_t nonce[], size_t nonce_len);
68 
69       /**
70       * Begin processing a message with a nonce
71       *
72       * @param nonce the per message nonce
73       */
74       template<typename Alloc>
start(const std::vector<uint8_t,Alloc> & nonce)75       void start(const std::vector<uint8_t, Alloc>& nonce)
76          {
77          start_msg(nonce.data(), nonce.size());
78          }
79 
80       /**
81       * Begin processing a message.
82       * @param nonce the per message nonce
83       * @param nonce_len length of nonce
84       */
start(const uint8_t nonce[],size_t nonce_len)85       void start(const uint8_t nonce[], size_t nonce_len)
86          {
87          start_msg(nonce, nonce_len);
88          }
89 
90       /**
91       * Begin processing a message.
92       */
start()93       void start()
94          {
95          return start_msg(nullptr, 0);
96          }
97 
98       /**
99       * Verify a MAC.
100       * @param in the MAC to verify as a byte array
101       * @param length the length of param in
102       * @return true if the MAC is valid, false otherwise
103       */
104       virtual bool verify_mac(const uint8_t in[], size_t length);
105 
106       /**
107       * Verify a MAC.
108       * @param in the MAC to verify as a byte array
109       * @return true if the MAC is valid, false otherwise
110       */
verify_mac(const std::vector<uint8_t> & in)111       virtual bool verify_mac(const std::vector<uint8_t>& in)
112          {
113          return verify_mac(in.data(), in.size());
114          }
115 
116       /**
117       * Verify a MAC.
118       * @param in the MAC to verify as a byte array
119       * @return true if the MAC is valid, false otherwise
120       */
verify_mac(const secure_vector<uint8_t> & in)121       virtual bool verify_mac(const secure_vector<uint8_t>& in)
122          {
123          return verify_mac(in.data(), in.size());
124          }
125 
126       /**
127       * Get a new object representing the same algorithm as *this
128       */
129       virtual MessageAuthenticationCode* clone() const = 0;
130 
131       /**
132       * @return provider information about this implementation. Default is "base",
133       * might also return "sse2", "avx2", "openssl", or some other arbitrary string.
134       */
provider()135       virtual std::string provider() const { return "base"; }
136 
137    };
138 
139 typedef MessageAuthenticationCode MAC;
140 
141 }
142 
143 #endif
144