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 20 #ifndef MBEDTLS_POLY1305_H 21 #define MBEDTLS_POLY1305_H 22 23 #if !defined(MBEDTLS_CONFIG_FILE) 24 #include "mbedtls/config.h" 25 #else 26 #include MBEDTLS_CONFIG_FILE 27 #endif 28 29 #include <stdint.h> 30 #include <stddef.h> 31 32 /** Invalid input parameter(s). */ 33 #define MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA -0x0057 34 35 /* MBEDTLS_ERR_POLY1305_FEATURE_UNAVAILABLE is deprecated and should not be 36 * used. */ 37 /** Feature not available. For example, s part of the API is not implemented. */ 38 #define MBEDTLS_ERR_POLY1305_FEATURE_UNAVAILABLE -0x0059 39 40 /* MBEDTLS_ERR_POLY1305_HW_ACCEL_FAILED is deprecated and should not be used. 41 */ 42 /** Poly1305 hardware accelerator failed. */ 43 #define MBEDTLS_ERR_POLY1305_HW_ACCEL_FAILED -0x005B 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 #if !defined(MBEDTLS_POLY1305_ALT) 50 51 typedef struct mbedtls_poly1305_context { 52 uint32_t r[4]; /** The value for 'r' (low 128 bits of the key). */ 53 uint32_t s[4]; /** The value for 's' (high 128 bits of the key). */ 54 uint32_t acc[5]; /** The accumulator number. */ 55 uint8_t queue[16]; /** The current partial block of data. */ 56 size_t 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