1 /** 2 * \file poly1305.h 3 * 4 * \brief This file contains Poly1305 definitions and functions. 5 * 6 * Poly1305 is a one-time message authenticator that can be used to 7 * authenticate messages. Poly1305-AES was created by Daniel 8 * Bernstein https://cr.yp.to/mac/poly1305-20050329.pdf The generic 9 * Poly1305 algorithm (not tied to AES) was also standardized in RFC 10 * 7539. 11 * 12 * \author Daniel King <damaki.gh@gmail.com> 13 */ 14 15 /* 16 * Copyright The Mbed TLS Contributors 17 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 18 * 19 * This file is provided under the Apache License 2.0, or the 20 * GNU General Public License v2.0 or later. 21 * 22 * ********** 23 * Apache License 2.0: 24 * 25 * Licensed under the Apache License, Version 2.0 (the "License"); you may 26 * not use this file except in compliance with the License. 27 * You may obtain a copy of the License at 28 * 29 * http://www.apache.org/licenses/LICENSE-2.0 30 * 31 * Unless required by applicable law or agreed to in writing, software 32 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 33 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 34 * See the License for the specific language governing permissions and 35 * limitations under the License. 36 * 37 * ********** 38 * 39 * ********** 40 * GNU General Public License v2.0 or later: 41 * 42 * This program is free software; you can redistribute it and/or modify 43 * it under the terms of the GNU General Public License as published by 44 * the Free Software Foundation; either version 2 of the License, or 45 * (at your option) any later version. 46 * 47 * This program is distributed in the hope that it will be useful, 48 * but WITHOUT ANY WARRANTY; without even the implied warranty of 49 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 50 * GNU General Public License for more details. 51 * 52 * You should have received a copy of the GNU General Public License along 53 * with this program; if not, write to the Free Software Foundation, Inc., 54 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 55 * 56 * ********** 57 */ 58 59 #ifndef MBEDTLS_POLY1305_H 60 #define MBEDTLS_POLY1305_H 61 62 #if !defined(MBEDTLS_CONFIG_FILE) 63 #include "config.h" 64 #else 65 #include MBEDTLS_CONFIG_FILE 66 #endif 67 68 #include <stdint.h> 69 #include <stddef.h> 70 71 #define MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA -0x0057 /**< Invalid input parameter(s). */ 72 73 /* MBEDTLS_ERR_POLY1305_FEATURE_UNAVAILABLE is deprecated and should not be 74 * used. */ 75 #define MBEDTLS_ERR_POLY1305_FEATURE_UNAVAILABLE -0x0059 /**< Feature not available. For example, s part of the API is not implemented. */ 76 77 /* MBEDTLS_ERR_POLY1305_HW_ACCEL_FAILED is deprecated and should not be used. 78 */ 79 #define MBEDTLS_ERR_POLY1305_HW_ACCEL_FAILED -0x005B /**< Poly1305 hardware accelerator failed. */ 80 81 #ifdef __cplusplus 82 extern "C" { 83 #endif 84 85 #if !defined(MBEDTLS_POLY1305_ALT) 86 87 typedef struct mbedtls_poly1305_context 88 { 89 uint32_t r[4]; /** The value for 'r' (low 128 bits of the key). */ 90 uint32_t s[4]; /** The value for 's' (high 128 bits of the key). */ 91 uint32_t acc[5]; /** The accumulator number. */ 92 uint8_t queue[16]; /** The current partial block of data. */ 93 size_t queue_len; /** The number of bytes stored in 'queue'. */ 94 } 95 mbedtls_poly1305_context; 96 97 #else /* MBEDTLS_POLY1305_ALT */ 98 #include "poly1305_alt.h" 99 #endif /* MBEDTLS_POLY1305_ALT */ 100 101 /** 102 * \brief This function initializes the specified Poly1305 context. 103 * 104 * It must be the first API called before using 105 * the context. 106 * 107 * It is usually followed by a call to 108 * \c mbedtls_poly1305_starts(), then one or more calls to 109 * \c mbedtls_poly1305_update(), then one call to 110 * \c mbedtls_poly1305_finish(), then finally 111 * \c mbedtls_poly1305_free(). 112 * 113 * \param ctx The Poly1305 context to initialize. This must 114 * not be \c NULL. 115 */ 116 void mbedtls_poly1305_init( mbedtls_poly1305_context *ctx ); 117 118 /** 119 * \brief This function releases and clears the specified 120 * Poly1305 context. 121 * 122 * \param ctx The Poly1305 context to clear. This may be \c NULL, in which 123 * case this function is a no-op. If it is not \c NULL, it must 124 * point to an initialized Poly1305 context. 125 */ 126 void mbedtls_poly1305_free( mbedtls_poly1305_context *ctx ); 127 128 /** 129 * \brief This function sets the one-time authentication key. 130 * 131 * \warning The key must be unique and unpredictable for each 132 * invocation of Poly1305. 133 * 134 * \param ctx The Poly1305 context to which the key should be bound. 135 * This must be initialized. 136 * \param key The buffer containing the \c 32 Byte (\c 256 Bit) key. 137 * 138 * \return \c 0 on success. 139 * \return A negative error code on failure. 140 */ 141 int mbedtls_poly1305_starts( mbedtls_poly1305_context *ctx, 142 const unsigned char key[32] ); 143 144 /** 145 * \brief This functions feeds an input buffer into an ongoing 146 * Poly1305 computation. 147 * 148 * It is called between \c mbedtls_cipher_poly1305_starts() and 149 * \c mbedtls_cipher_poly1305_finish(). 150 * It can be called repeatedly to process a stream of data. 151 * 152 * \param ctx The Poly1305 context to use for the Poly1305 operation. 153 * This must be initialized and bound to a key. 154 * \param ilen The length of the input data in Bytes. 155 * Any value is accepted. 156 * \param input The buffer holding the input data. 157 * This pointer can be \c NULL if `ilen == 0`. 158 * 159 * \return \c 0 on success. 160 * \return A negative error code on failure. 161 */ 162 int mbedtls_poly1305_update( mbedtls_poly1305_context *ctx, 163 const unsigned char *input, 164 size_t ilen ); 165 166 /** 167 * \brief This function generates the Poly1305 Message 168 * Authentication Code (MAC). 169 * 170 * \param ctx The Poly1305 context to use for the Poly1305 operation. 171 * This must be initialized and bound to a key. 172 * \param mac The buffer to where the MAC is written. This must 173 * be a writable buffer of length \c 16 Bytes. 174 * 175 * \return \c 0 on success. 176 * \return A negative error code on failure. 177 */ 178 int mbedtls_poly1305_finish( mbedtls_poly1305_context *ctx, 179 unsigned char mac[16] ); 180 181 /** 182 * \brief This function calculates the Poly1305 MAC of the input 183 * buffer with the provided key. 184 * 185 * \warning The key must be unique and unpredictable for each 186 * invocation of Poly1305. 187 * 188 * \param key The buffer containing the \c 32 Byte (\c 256 Bit) key. 189 * \param ilen The length of the input data in Bytes. 190 * Any value is accepted. 191 * \param input The buffer holding the input data. 192 * This pointer can be \c NULL if `ilen == 0`. 193 * \param mac The buffer to where the MAC is written. This must be 194 * a writable buffer of length \c 16 Bytes. 195 * 196 * \return \c 0 on success. 197 * \return A negative error code on failure. 198 */ 199 int mbedtls_poly1305_mac( const unsigned char key[32], 200 const unsigned char *input, 201 size_t ilen, 202 unsigned char mac[16] ); 203 204 #if defined(MBEDTLS_SELF_TEST) 205 /** 206 * \brief The Poly1305 checkup routine. 207 * 208 * \return \c 0 on success. 209 * \return \c 1 on failure. 210 */ 211 int mbedtls_poly1305_self_test( int verbose ); 212 #endif /* MBEDTLS_SELF_TEST */ 213 214 #ifdef __cplusplus 215 } 216 #endif 217 218 #endif /* MBEDTLS_POLY1305_H */ 219