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