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 18 * 19 * Licensed under the Apache License, Version 2.0 (the "License"); you may 20 * not use this file except in compliance with the License. 21 * You may obtain a copy of the License at 22 * 23 * http://www.apache.org/licenses/LICENSE-2.0 24 * 25 * Unless required by applicable law or agreed to in writing, software 26 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 27 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 28 * See the License for the specific language governing permissions and 29 * limitations under the License. 30 */ 31 32 #ifndef MBEDTLS_POLY1305_H 33 #define MBEDTLS_POLY1305_H 34 #include "mbedtls/private_access.h" 35 36 #include "mbedtls/build_info.h" 37 38 #include <stdint.h> 39 #include <stddef.h> 40 41 /** Invalid input parameter(s). */ 42 #define MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA -0x0057 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 #if !defined(MBEDTLS_POLY1305_ALT) 49 50 typedef struct mbedtls_poly1305_context 51 { 52 uint32_t MBEDTLS_PRIVATE(r)[4]; /** The value for 'r' (low 128 bits of the key). */ 53 uint32_t MBEDTLS_PRIVATE(s)[4]; /** The value for 's' (high 128 bits of the key). */ 54 uint32_t MBEDTLS_PRIVATE(acc)[5]; /** The accumulator number. */ 55 uint8_t MBEDTLS_PRIVATE(queue)[16]; /** The current partial block of data. */ 56 size_t MBEDTLS_PRIVATE(queue_len); /** The number of bytes stored in 'queue'. */ 57 } 58 mbedtls_poly1305_context; 59 60 #else /* MBEDTLS_POLY1305_ALT */ 61 #include "poly1305_alt.h" 62 #endif /* MBEDTLS_POLY1305_ALT */ 63 64 /** 65 * \brief This function initializes the specified Poly1305 context. 66 * 67 * It must be the first API called before using 68 * the context. 69 * 70 * It is usually followed by a call to 71 * \c mbedtls_poly1305_starts(), then one or more calls to 72 * \c mbedtls_poly1305_update(), then one call to 73 * \c mbedtls_poly1305_finish(), then finally 74 * \c mbedtls_poly1305_free(). 75 * 76 * \param ctx The Poly1305 context to initialize. This must 77 * not be \c NULL. 78 */ 79 void mbedtls_poly1305_init( mbedtls_poly1305_context *ctx ); 80 81 /** 82 * \brief This function releases and clears the specified 83 * Poly1305 context. 84 * 85 * \param ctx The Poly1305 context to clear. This may be \c NULL, in which 86 * case this function is a no-op. If it is not \c NULL, it must 87 * point to an initialized Poly1305 context. 88 */ 89 void mbedtls_poly1305_free( mbedtls_poly1305_context *ctx ); 90 91 /** 92 * \brief This function sets the one-time authentication key. 93 * 94 * \warning The key must be unique and unpredictable for each 95 * invocation of Poly1305. 96 * 97 * \param ctx The Poly1305 context to which the key should be bound. 98 * This must be initialized. 99 * \param key The buffer containing the \c 32 Byte (\c 256 Bit) key. 100 * 101 * \return \c 0 on success. 102 * \return A negative error code on failure. 103 */ 104 int mbedtls_poly1305_starts( mbedtls_poly1305_context *ctx, 105 const unsigned char key[32] ); 106 107 /** 108 * \brief This functions feeds an input buffer into an ongoing 109 * Poly1305 computation. 110 * 111 * It is called between \c mbedtls_cipher_poly1305_starts() and 112 * \c mbedtls_cipher_poly1305_finish(). 113 * It can be called repeatedly to process a stream of data. 114 * 115 * \param ctx The Poly1305 context to use for the Poly1305 operation. 116 * This must be initialized and bound to a key. 117 * \param ilen The length of the input data in Bytes. 118 * Any value is accepted. 119 * \param input The buffer holding the input data. 120 * This pointer can be \c NULL if `ilen == 0`. 121 * 122 * \return \c 0 on success. 123 * \return A negative error code on failure. 124 */ 125 int mbedtls_poly1305_update( mbedtls_poly1305_context *ctx, 126 const unsigned char *input, 127 size_t ilen ); 128 129 /** 130 * \brief This function generates the Poly1305 Message 131 * Authentication Code (MAC). 132 * 133 * \param ctx The Poly1305 context to use for the Poly1305 operation. 134 * This must be initialized and bound to a key. 135 * \param mac The buffer to where the MAC is written. This must 136 * be a writable buffer of length \c 16 Bytes. 137 * 138 * \return \c 0 on success. 139 * \return A negative error code on failure. 140 */ 141 int mbedtls_poly1305_finish( mbedtls_poly1305_context *ctx, 142 unsigned char mac[16] ); 143 144 /** 145 * \brief This function calculates the Poly1305 MAC of the input 146 * buffer with the provided key. 147 * 148 * \warning The key must be unique and unpredictable for each 149 * invocation of Poly1305. 150 * 151 * \param key The buffer containing the \c 32 Byte (\c 256 Bit) key. 152 * \param ilen The length of the input data in Bytes. 153 * Any value is accepted. 154 * \param input The buffer holding the input data. 155 * This pointer can be \c NULL if `ilen == 0`. 156 * \param mac The buffer to where the MAC is written. This must be 157 * a writable buffer of length \c 16 Bytes. 158 * 159 * \return \c 0 on success. 160 * \return A negative error code on failure. 161 */ 162 int mbedtls_poly1305_mac( const unsigned char key[32], 163 const unsigned char *input, 164 size_t ilen, 165 unsigned char mac[16] ); 166 167 #if defined(MBEDTLS_SELF_TEST) 168 /** 169 * \brief The Poly1305 checkup routine. 170 * 171 * \return \c 0 on success. 172 * \return \c 1 on failure. 173 */ 174 int mbedtls_poly1305_self_test( int verbose ); 175 #endif /* MBEDTLS_SELF_TEST */ 176 177 #ifdef __cplusplus 178 } 179 #endif 180 181 #endif /* MBEDTLS_POLY1305_H */ 182
