1/* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements.  See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License.  You may obtain a copy of the License at
7 *
8 *     http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16/*
17   SipHash reference C implementation
18   Copyright (c) 2012-2014 Jean-Philippe Aumasson
19   <jeanphilippe.aumasson@gmail.com>
20   Copyright (c) 2012-2014 Daniel J. Bernstein <djb@cr.yp.to>
21   To the extent possible under law, the author(s) have dedicated all copyright
22   and related and neighboring rights to this software to the public domain
23   worldwide. This software is distributed without any warranty.
24   You should have received a copy of the CC0 Public Domain Dedication along
25   with this software. If not, see
26   <http://creativecommons.org/publicdomain/zero/1.0/>.
27 */
28
29#ifndef APR_SIPHASH_H
30#define APR_SIPHASH_H
31
32#include "apr.h"
33#include "apu.h"
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39/**
40 * @file apr_siphash.h
41 * @brief APR-UTIL siphash library
42 *        "SipHash-c-d is a family of pseudorandom functions (a.k.a. keyed
43 *        hash functions) optimized for speed on short messages", designed by
44 *        Jean-Philippe Aumasson and Daniel J. Bernstein. It generates a 64bit
45 *        hash (or MAC) from the message and a 128bit key.
46 *        See http://cr.yp.to/siphash/siphash-20120620.pdf for the details,
47 *        c is the number of compression rounds, d the number of finalization
48 *        rounds; we also define fast implementations for c = 2 with d = 4 (aka
49 *        siphash-2-4), and c = 4 with d = 8 (aka siphash-4-8), as recommended
50 *        parameters per the authors.
51 */
52
53/** size of the siphash digest */
54#define APR_SIPHASH_DSIZE 8
55
56/** size of the siphash key */
57#define APR_SIPHASH_KSIZE 16
58
59
60/**
61 * @brief Computes SipHash-c-d, producing a 64bit (APR_SIPHASH_DSIZE) hash
62 * from a message and a 128bit (APR_SIPHASH_KSIZE) secret key.
63 * @param src The message
64 * @param len The length of the message
65 * @param key The secret key
66 * @param c   The number of compression rounds
67 * @param d   The number of finalization rounds
68 * @return The hash value as a 64bit unsigned integer
69 */
70APU_DECLARE(apr_uint64_t) apr_siphash(const void *src, apr_size_t len,
71                              const unsigned char key[APR_SIPHASH_KSIZE],
72                                      unsigned int c, unsigned int d);
73
74/**
75 * @brief Computes SipHash-c-d, producing a 64bit (APR_SIPHASH_DSIZE) hash
76 * from a message and a 128bit (APR_SIPHASH_KSIZE) secret key, into a possibly
77 * unaligned buffer (using the little endian representation as defined by the
78 * authors for interoperabilty) usable as a MAC.
79 * @param out The output buffer (or MAC)
80 * @param src The message
81 * @param len The length of the message
82 * @param key The secret key
83 * @param c   The number of compression rounds
84 * @param d   The number of finalization rounds
85 * @return The hash value as a 64bit unsigned integer
86 */
87APU_DECLARE(void) apr_siphash_auth(unsigned char out[APR_SIPHASH_DSIZE],
88                                   const void *src, apr_size_t len,
89                             const unsigned char key[APR_SIPHASH_KSIZE],
90                                   unsigned int c, unsigned int d);
91
92/**
93 * @brief Computes SipHash-2-4, producing a 64bit (APR_SIPHASH_DSIZE) hash
94 * from a message and a 128bit (APR_SIPHASH_KSIZE) secret key.
95 * @param src The message to hash
96 * @param len The length of the message
97 * @param key The secret key
98 * @return The hash value as a 64bit unsigned integer
99 */
100APU_DECLARE(apr_uint64_t) apr_siphash24(const void *src, apr_size_t len,
101                               const unsigned char key[APR_SIPHASH_KSIZE]);
102
103/**
104 * @brief Computes SipHash-2-4, producing a 64bit (APR_SIPHASH_DSIZE) hash
105 * from a message and a 128bit (APR_SIPHASH_KSIZE) secret key, into a possibly
106 * unaligned buffer (using the little endian representation as defined by the
107 * authors for interoperabilty) usable as a MAC.
108 * @param out The output buffer (or MAC)
109 * @param src The message
110 * @param len The length of the message
111 * @param key The secret key
112 * @return The hash value as a 64bit unsigned integer
113 */
114APU_DECLARE(void) apr_siphash24_auth(unsigned char out[APR_SIPHASH_DSIZE],
115                                     const void *src, apr_size_t len,
116                               const unsigned char key[APR_SIPHASH_KSIZE]);
117
118/**
119 * @brief Computes SipHash-4-8, producing a 64bit (APR_SIPHASH_DSIZE) hash
120 * from a message and a 128bit (APR_SIPHASH_KSIZE) secret key.
121 * @param src The message
122 * @param len The length of the message
123 * @param key The secret key
124 * @return The hash value as a 64bit unsigned integer
125 */
126APU_DECLARE(apr_uint64_t) apr_siphash48(const void *src, apr_size_t len,
127                               const unsigned char key[APR_SIPHASH_KSIZE]);
128
129/**
130 * @brief Computes SipHash-4-8, producing a 64bit (APR_SIPHASH_DSIZE) hash
131 * from a message and a 128bit (APR_SIPHASH_KSIZE) secret key, into a possibly
132 * unaligned buffer (using the little endian representation as defined by the
133 * authors for interoperabilty) usable as a MAC.
134 * @param out The output buffer (or MAC)
135 * @param src The message
136 * @param len The length of the message
137 * @param key The secret key
138 * @return The hash value as a 64bit unsigned integer
139 */
140APU_DECLARE(void) apr_siphash48_auth(unsigned char out[APR_SIPHASH_DSIZE],
141                                     const void *src, apr_size_t len,
142                               const unsigned char key[APR_SIPHASH_KSIZE]);
143
144#ifdef __cplusplus
145}
146#endif
147
148#endif  /* APR_SIPHASH_H */
149