Crypto++  8.6
Free C++ class library of cryptographic schemes
siphash.h
Go to the documentation of this file.
1 // siphash.h - written and placed in public domain by Jeffrey Walton.
2 
3 /// \file siphash.h
4 /// \brief Classes for SipHash message authentication code
5 /// \details SipHash computes a 64-bit or 128-bit message authentication code from a variable-length
6 /// message and 128-bit secret key. It was designed to be efficient even for short inputs, with
7 /// performance comparable to non-cryptographic hash functions.
8 /// \details To create a SipHash-2-4 object with a 64-bit MAC use code similar to the following.
9 /// <pre> SecByteBlock key(16);
10 /// prng.GenerateBlock(key, key.size());
11 ///
12 /// SipHash<2,4,false> hash(key, key.size());
13 /// hash.Update(...);
14 /// hash.Final(...);</pre>
15 /// \details To create a SipHash-2-4 object with a 128-bit MAC use code similar to the following.
16 /// <pre> SecByteBlock key(16);
17 /// prng.GenerateBlock(key, key.size());
18 ///
19 /// SipHash<2,4,true> hash(key, key.size());
20 /// hash.Update(...);
21 /// hash.Final(...);</pre>
22 /// \sa Jean-Philippe Aumasson and Daniel J. Bernstein <A HREF="http://131002.net/siphash/siphash.pdf">SipHash:
23 /// a fast short-input PRF</A>
24 /// \since Crypto++ 6.0
25 
26 #ifndef CRYPTOPP_SIPHASH_H
27 #define CRYPTOPP_SIPHASH_H
28 
29 #include "cryptlib.h"
30 #include "secblock.h"
31 #include "seckey.h"
32 #include "misc.h"
33 
34 NAMESPACE_BEGIN(CryptoPP)
35 
36 /// \brief SipHash message authentication code information
37 /// \tparam T_128bit flag indicating 128-bit (true) versus 64-bit (false) digest size
38 template <bool T_128bit>
39 class SipHash_Info : public FixedKeyLength<16>
40 {
41 public:
42  CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "SipHash";}
43  CRYPTOPP_CONSTANT(DIGESTSIZE = (T_128bit ? 16 : 8));
44 };
45 
46 /// \brief SipHash message authentication code base class
47 /// \tparam C the number of compression rounds
48 /// \tparam D the number of finalization rounds
49 /// \tparam T_128bit flag indicating 128-bit (true) versus 64-bit (false) digest size
50 template <unsigned int C, unsigned int D, bool T_128bit>
51 class SipHash_Base : public MessageAuthenticationCode, public SipHash_Info<T_128bit>
52 {
53 public:
54  static std::string StaticAlgorithmName() {
55  return std::string(SipHash_Info<T_128bit>::StaticAlgorithmName())+"-"+IntToString(C)+"-"+IntToString(D);
56  }
57 
58  virtual ~SipHash_Base() {}
59 
60  SipHash_Base() : m_idx(0) {}
61 
62  virtual unsigned int DigestSize() const
64  virtual size_t MinKeyLength() const
66  virtual size_t MaxKeyLength() const
68  virtual size_t DefaultKeyLength() const
70  virtual size_t GetValidKeyLength(size_t keylength) const
71  {CRYPTOPP_UNUSED(keylength); return SipHash_Info<T_128bit>::DEFAULT_KEYLENGTH;}
72  virtual IV_Requirement IVRequirement() const
74  virtual unsigned int IVSize() const
75  {return 0;}
76  virtual unsigned int OptimalBlockSize() const
77  {return sizeof(word64);}
78  virtual unsigned int OptimalDataAlignment () const
79  {return GetAlignmentOf<word64>();}
80 
81  virtual void Update(const byte *input, size_t length);
82  virtual void TruncatedFinal(byte *digest, size_t digestSize);
83 
84 protected:
85 
86  virtual void UncheckedSetKey(const byte *key, unsigned int length, const NameValuePairs &params);
87  virtual void Restart();
88 
89  inline void SIPROUND()
90  {
91  m_v[0] += m_v[1];
92  m_v[1] = rotlConstant<13>(m_v[1]);
93  m_v[1] ^= m_v[0];
94  m_v[0] = rotlConstant<32>(m_v[0]);
95  m_v[2] += m_v[3];
96  m_v[3] = rotlConstant<16>(m_v[3]);
97  m_v[3] ^= m_v[2];
98  m_v[0] += m_v[3];
99  m_v[3] = rotlConstant<21>(m_v[3]);
100  m_v[3] ^= m_v[0];
101  m_v[2] += m_v[1];
102  m_v[1] = rotlConstant<17>(m_v[1]);
103  m_v[1] ^= m_v[2];
104  m_v[2] = rotlConstant<32>(m_v[2]);
105  }
106 
107 private:
111 
112  // Tail bytes
114  size_t m_idx;
115 };
116 
117 /// \brief SipHash message authentication code
118 /// \tparam C the number of compression rounds
119 /// \tparam D the number of finalization rounds
120 /// \tparam T_128bit flag indicating 128-bit (true) versus 64-bit (false) digest size
121 /// \details SipHash computes a 64-bit or 128-bit message authentication code from a variable-length
122 /// message and 128-bit secret key. It was designed to be efficient even for short inputs, with
123 /// performance comparable to non-cryptographic hash functions.
124 /// \details To create a SipHash-2-4 object with a 64-bit MAC use code similar to the following.
125 /// <pre> SecByteBlock key(16);
126 /// prng.GenerateBlock(key, key.size());
127 ///
128 /// SipHash<2,4,false> hash(key, key.size());
129 /// hash.Update(...);
130 /// hash.Final(...);</pre>
131 /// \details To create a SipHash-2-4 object with a 128-bit MAC use code similar to the following.
132 /// <pre> SecByteBlock key(16);
133 /// prng.GenerateBlock(key, key.size());
134 ///
135 /// SipHash<2,4,true> hash(key, key.size());
136 /// hash.Update(...);
137 /// hash.Final(...);</pre>
138 /// \sa Jean-Philippe Aumasson and Daniel J. Bernstein <A HREF="http://131002.net/siphash/siphash.pdf">SipHash:
139 /// a fast short-input PRF</A>
140 /// \since Crypto++ 6.0
141 template <unsigned int C=2, unsigned int D=4, bool T_128bit=false>
142 class SipHash : public SipHash_Base<C, D, T_128bit>
143 {
144 public:
145  /// \brief Create a SipHash
147  {this->UncheckedSetKey(NULLPTR, 0, g_nullNameValuePairs);}
148  /// \brief Create a SipHash
149  /// \param key a byte array used to key the cipher
150  /// \param length the size of the byte array, in bytes
151  SipHash(const byte *key, unsigned int length)
152  {this->ThrowIfInvalidKeyLength(length);
153  this->UncheckedSetKey(key, length, g_nullNameValuePairs);}
154 };
155 
156 template <unsigned int C, unsigned int D, bool T_128bit>
157 void SipHash_Base<C,D,T_128bit>::Update(const byte *input, size_t length)
158 {
159  CRYPTOPP_ASSERT((input && length) || !length);
160  if (!length) return;
161 
162  if (m_idx)
163  {
164  size_t head = STDMIN(size_t(8U-m_idx), length);
165  memcpy(m_acc+m_idx, input, head);
166  m_idx += head; input += head; length -= head;
167 
168  if (m_idx == 8)
169  {
170  word64 m = GetWord<word64>(true, LITTLE_ENDIAN_ORDER, m_acc);
171  m_v[3] ^= m;
172  for (unsigned int i = 0; i < C; ++i)
173  SIPROUND();
174 
175  m_v[0] ^= m;
176  m_b[0] += 8;
177 
178  m_idx = 0;
179  }
180  }
181 
182  while (length >= 8)
183  {
184  word64 m = GetWord<word64>(false, LITTLE_ENDIAN_ORDER, input);
185  m_v[3] ^= m;
186  for (unsigned int i = 0; i < C; ++i)
187  SIPROUND();
188 
189  m_v[0] ^= m;
190  m_b[0] += 8;
191 
192  input += 8;
193  length -= 8;
194  }
195 
196  CRYPTOPP_ASSERT(length < 8);
197  size_t tail = length % 8;
198  if (tail)
199  {
200  memcpy(m_acc+m_idx, input, tail);
201  m_idx += tail;
202  }
203 }
204 
205 template <unsigned int C, unsigned int D, bool T_128bit>
206 void SipHash_Base<C,D,T_128bit>::TruncatedFinal(byte *digest, size_t digestSize)
207 {
208  CRYPTOPP_ASSERT(digest); // Pointer is valid
209 
210  ThrowIfInvalidTruncatedSize(digestSize);
211 
212  // The high octet holds length and is digested mod 256
213  m_b[0] += m_idx; m_b[0] <<= 56U;
214  switch (m_idx)
215  {
216  case 7:
217  m_b[0] |= ((word64)m_acc[6]) << 48;
218  // fall through
219  case 6:
220  m_b[0] |= ((word64)m_acc[5]) << 40;
221  // fall through
222  case 5:
223  m_b[0] |= ((word64)m_acc[4]) << 32;
224  // fall through
225  case 4:
226  m_b[0] |= ((word64)m_acc[3]) << 24;
227  // fall through
228  case 3:
229  m_b[0] |= ((word64)m_acc[2]) << 16;
230  // fall through
231  case 2:
232  m_b[0] |= ((word64)m_acc[1]) << 8;
233  // fall through
234  case 1:
235  m_b[0] |= ((word64)m_acc[0]);
236  // fall through
237  case 0:
238  break;
239  }
240 
241  m_v[3] ^= m_b[0];
242 
243  for (unsigned int i=0; i<C; i++)
244  SIPROUND();
245 
246  m_v[0] ^= m_b[0];
247 
248  if (T_128bit)
249  m_v[2] ^= 0xee;
250  else
251  m_v[2] ^= 0xff;
252 
253  for (unsigned int i=0; i<D; i++)
254  SIPROUND();
255 
256  m_b[0] = m_v[0] ^ m_v[1] ^ m_v[2] ^ m_v[3];
258 
259  if (T_128bit)
260  {
261  m_v[1] ^= 0xdd;
262  for (unsigned int i = 0; i<D; ++i)
263  SIPROUND();
264 
265  m_b[1] = m_v[0] ^ m_v[1] ^ m_v[2] ^ m_v[3];
267  }
268 
269  memcpy_s(digest, digestSize, m_b.begin(), STDMIN(digestSize, (size_t)SipHash_Info<T_128bit>::DIGESTSIZE));
270  Restart();
271 }
272 
273 template <unsigned int C, unsigned int D, bool T_128bit>
274 void SipHash_Base<C,D,T_128bit>::UncheckedSetKey(const byte *key, unsigned int length, const NameValuePairs &params)
275 {
276  CRYPTOPP_UNUSED(params);
277  if (key && length)
278  {
279  m_k[0] = GetWord<word64>(false, LITTLE_ENDIAN_ORDER, key);
280  m_k[1] = GetWord<word64>(false, LITTLE_ENDIAN_ORDER, key+8);
281  }
282  else
283  {
284  // Avoid Coverity finding
285  m_k[0] = m_k[1] = 0;
286  }
287  Restart();
288 }
289 
290 template <unsigned int C, unsigned int D, bool T_128bit>
292 {
293  m_v[0] = W64LIT(0x736f6d6570736575);
294  m_v[1] = W64LIT(0x646f72616e646f6d);
295  m_v[2] = W64LIT(0x6c7967656e657261);
296  m_v[3] = W64LIT(0x7465646279746573);
297 
298  m_v[3] ^= m_k[1];
299  m_v[2] ^= m_k[0];
300  m_v[1] ^= m_k[1];
301  m_v[0] ^= m_k[0];
302 
303  if (T_128bit)
304  {
305  m_v[1] ^= 0xee;
306  }
307 
308  m_idx = 0;
309  m_b[0] = 0;
310 }
311 
312 NAMESPACE_END
313 
314 #endif // CRYPTOPP_SIPHASH_H
SipHash
SipHash message authentication code.
Definition: siphash.h:142
W64LIT
#define W64LIT(x)
Declare an unsigned word64.
Definition: config_int.h:119
SimpleKeyingInterface::NOT_RESYNCHRONIZABLE
@ NOT_RESYNCHRONIZABLE
The object does not use an IV.
Definition: cryptlib.h:729
secblock.h
Classes and functions for secure memory allocations.
CRYPTOPP_ASSERT
#define CRYPTOPP_ASSERT(exp)
Debugging and diagnostic assertion.
Definition: trap.h:68
SipHash_Base::GetValidKeyLength
virtual size_t GetValidKeyLength(size_t keylength) const
Returns a valid key length for the algorithm.
Definition: siphash.h:70
SipHash_Base
SipHash message authentication code base class.
Definition: siphash.h:51
LITTLE_ENDIAN_ORDER
@ LITTLE_ENDIAN_ORDER
byte order is little-endian
Definition: cryptlib.h:145
SipHash::SipHash
SipHash(const byte *key, unsigned int length)
Create a SipHash.
Definition: siphash.h:151
SipHash_Base::OptimalBlockSize
virtual unsigned int OptimalBlockSize() const
Provides the input block size most efficient for this hash.
Definition: siphash.h:76
word64
unsigned long long word64
64-bit unsigned datatype
Definition: config_int.h:91
SipHash_Base::MaxKeyLength
virtual size_t MaxKeyLength() const
Returns largest valid key length.
Definition: siphash.h:66
SimpleKeyingInterface::IV_Requirement
IV_Requirement
Secure IVs requirements as enumerated values.
Definition: cryptlib.h:719
SipHash_Base::OptimalDataAlignment
virtual unsigned int OptimalDataAlignment() const
Provides input and output data alignment for optimal performance.
Definition: siphash.h:78
FixedKeyLength
Inherited by keyed algorithms with fixed key length.
Definition: seckey.h:124
misc.h
Utility functions for the Crypto++ library.
STDMIN
const T & STDMIN(const T &a, const T &b)
Replacement function for std::min.
Definition: misc.h:655
SipHash_Info
SipHash message authentication code information.
Definition: siphash.h:39
SipHash_Base::DigestSize
virtual unsigned int DigestSize() const
Provides the digest size of the hash.
Definition: siphash.h:62
IntToString
std::string IntToString(T value, unsigned int base=10)
Converts a value to a string.
Definition: misc.h:724
SipHash_Base::Update
virtual void Update(const byte *input, size_t length)
Updates a hash with additional input.
Definition: siphash.h:157
seckey.h
Classes and functions for implementing secret key algorithms.
SipHash_Base::IVSize
virtual unsigned int IVSize() const
Returns length of the IV accepted by this object.
Definition: siphash.h:74
ConditionalByteReverse
T ConditionalByteReverse(ByteOrder order, T value)
Reverses bytes in a value depending upon endianness.
Definition: misc.h:2208
FixedSizeSecBlock< word64, 4 >
SipHash::SipHash
SipHash()
Create a SipHash.
Definition: siphash.h:146
SipHash_Base::MinKeyLength
virtual size_t MinKeyLength() const
Returns smallest valid key length.
Definition: siphash.h:64
g_nullNameValuePairs
const NameValuePairs & g_nullNameValuePairs
An empty set of name-value pairs.
Definition: cryptlib.h:529
CryptoPP
Crypto++ library namespace.
SipHash_Base::TruncatedFinal
virtual void TruncatedFinal(byte *digest, size_t digestSize)
Computes the hash of the current message.
Definition: siphash.h:206
MessageAuthenticationCode
Interface for message authentication codes.
Definition: cryptlib.h:1298
memcpy_s
void memcpy_s(void *dest, size_t sizeInBytes, const void *src, size_t count)
Bounds checking replacement for memcpy()
Definition: misc.h:525
SipHash_Base::IVRequirement
virtual IV_Requirement IVRequirement() const
Minimal requirement for secure IVs.
Definition: siphash.h:72
NameValuePairs
Interface for retrieving values given their names.
Definition: cryptlib.h:321
cryptlib.h
Abstract base classes that provide a uniform interface to this library.
SipHash_Base::DefaultKeyLength
virtual size_t DefaultKeyLength() const
Returns default key length.
Definition: siphash.h:68