text: /**
   * \file chacha20.h
   *
   * \brief   This file contains ChaCha20 definitions and functions.
   *
   *          ChaCha20 is a stream cipher that can encrypt and decrypt
   *          information. ChaCha was created by Daniel Bernstein as a variant of
   *          its Salsa cipher https://cr.yp.to/chacha/chacha-20080128.pdf
   *          ChaCha20 is the variant with 20 rounds, that was also standardized
   *          in RFC 7539.
   *
   * \author Daniel King <damaki.gh@gmail.com>
   */
  
  /*  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
   *  SPDX-License-Identifier: Apache-2.0
   *
   *  Licensed under the Apache License, Version 2.0 (the "License"); you may
   *  not use this file except in compliance with the License.
   *  You may obtain a copy of the License at
   *
   *  http://www.apache.org/licenses/LICENSE-2.0
   *
   *  Unless required by applicable law or agreed to in writing, software
   *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
   *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   *  See the License for the specific language governing permissions and
   *  limitations under the License.
   *
   *  This file is part of Mbed TLS (https://tls.mbed.org)
   */
  
  #ifndef MBEDTLS_CHACHA20_H
  #define MBEDTLS_CHACHA20_H
  
  #if !defined(MBEDTLS_CONFIG_FILE)
  #include "config.h"
  #else
  #include MBEDTLS_CONFIG_FILE
  #endif
  
  #include <stdint.h>
  #include <stddef.h>
  
  #define MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA         -0x0051 /**< Invalid input parameter(s). */
  
  /* MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE is deprecated and should not be
   * used. */
  #define MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE    -0x0053 /**< Feature not available. For example, s part of the API is not implemented. */
  
  /* MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED is deprecated and should not be used.
   */
  #define MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED        -0x0055  /**< Chacha20 hardware accelerator failed. */
  
  #ifdef __cplusplus
  extern "C" {
  #endif
  
  #if !defined(MBEDTLS_CHACHA20_ALT)
  
  typedef struct mbedtls_chacha20_context
  {
      uint32_t state[16];          /*! The state (before round operations). */
      uint8_t  keystream8[64];     /*! Leftover keystream bytes. */
      size_t keystream_bytes_used; /*! Number of keystream bytes already used. */
  }
  mbedtls_chacha20_context;
  
  #else  /* MBEDTLS_CHACHA20_ALT */
  #include "chacha20_alt.h"
  #endif /* MBEDTLS_CHACHA20_ALT */
  
  /**
   * \brief           This function initializes the specified ChaCha20 context.
   *
   *                  It must be the first API called before using
   *                  the context.
   *
   *                  It is usually followed by calls to
   *                  \c mbedtls_chacha20_setkey() and
   *                  \c mbedtls_chacha20_starts(), then one or more calls to
   *                  to \c mbedtls_chacha20_update(), and finally to
   *                  \c mbedtls_chacha20_free().
   *
   * \param ctx       The ChaCha20 context to initialize.
   *                  This must not be \c NULL.
   */
  void mbedtls_chacha20_init( mbedtls_chacha20_context *ctx );
  
  /**
   * \brief           This function releases and clears the specified
   *                  ChaCha20 context.
   *
   * \param ctx       The ChaCha20 context to clear. This may be \c NULL,
   *                  in which case this function is a no-op. If it is not
   *                  \c NULL, it must point to an initialized context.
   *
   */
  void mbedtls_chacha20_free( mbedtls_chacha20_context *ctx );
  
  /**
   * \brief           This function sets the encryption/decryption key.
   *
   * \note            After using this function, you must also call
   *                  \c mbedtls_chacha20_starts() to set a nonce before you
   *                  start encrypting/decrypting data with
   *                  \c mbedtls_chacha_update().
   *
   * \param ctx       The ChaCha20 context to which the key should be bound.
   *                  It must be initialized.
   * \param key       The encryption/decryption key. This must be \c 32 Bytes
   *                  in length.
   *
   * \return          \c 0 on success.
   * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or key is NULL.
   */
  int mbedtls_chacha20_setkey( mbedtls_chacha20_context *ctx,
                               const unsigned char key[32] );
  
  /**
   * \brief           This function sets the nonce and initial counter value.
   *
   * \note            A ChaCha20 context can be re-used with the same key by
   *                  calling this function to change the nonce.
   *
   * \warning         You must never use the same nonce twice with the same key.
   *                  This would void any confidentiality guarantees for the
   *                  messages encrypted with the same nonce and key.
   *
   * \param ctx       The ChaCha20 context to which the nonce should be bound.
   *                  It must be initialized and bound to a key.
   * \param nonce     The nonce. This must be \c 12 Bytes in size.
   * \param counter   The initial counter value. This is usually \c 0.
   *
   * \return          \c 0 on success.
   * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or nonce is
   *                  NULL.
   */
  int mbedtls_chacha20_starts( mbedtls_chacha20_context* ctx,
                               const unsigned char nonce[12],
                               uint32_t counter );
  
  /**
   * \brief           This function encrypts or decrypts data.
   *
   *                  Since ChaCha20 is a stream cipher, the same operation is
   *                  used for encrypting and decrypting data.
   *
   * \note            The \p input and \p output pointers must either be equal or
   *                  point to non-overlapping buffers.
   *
   * \note            \c mbedtls_chacha20_setkey() and
   *                  \c mbedtls_chacha20_starts() must be called at least once
   *                  to setup the context before this function can be called.
   *
   * \note            This function can be called multiple times in a row in
   *                  order to encrypt of decrypt data piecewise with the same
   *                  key and nonce.
   *
   * \param ctx       The ChaCha20 context to use for encryption or decryption.
   *                  It must be initialized and bound to a key and nonce.
   * \param size      The length of the input data in Bytes.
   * \param input     The buffer holding the input data.
   *                  This pointer can be \c NULL if `size == 0`.
   * \param output    The buffer holding the output data.
   *                  This must be able to hold \p size Bytes.
   *                  This pointer can be \c NULL if `size == 0`.
   *
   * \return          \c 0 on success.
   * \return          A negative error code on failure.
   */
  int mbedtls_chacha20_update( mbedtls_chacha20_context *ctx,
                               size_t size,
                               const unsigned char *input,
                               unsigned char *output );
  
  /**
   * \brief           This function encrypts or decrypts data with ChaCha20 and
   *                  the given key and nonce.
   *
   *                  Since ChaCha20 is a stream cipher, the same operation is
   *                  used for encrypting and decrypting data.
   *
   * \warning         You must never use the same (key, nonce) pair more than
   *                  once. This would void any confidentiality guarantees for
   *                  the messages encrypted with the same nonce and key.
   *
   * \note            The \p input and \p output pointers must either be equal or
   *                  point to non-overlapping buffers.
   *
   * \param key       The encryption/decryption key.
   *                  This must be \c 32 Bytes in length.
   * \param nonce     The nonce. This must be \c 12 Bytes in size.
   * \param counter   The initial counter value. This is usually \c 0.
   * \param size      The length of the input data in Bytes.
   * \param input     The buffer holding the input data.
   *                  This pointer can be \c NULL if `size == 0`.
   * \param output    The buffer holding the output data.
   *                  This must be able to hold \p size Bytes.
   *                  This pointer can be \c NULL if `size == 0`.
   *
   * \return          \c 0 on success.
   * \return          A negative error code on failure.
   */
  int mbedtls_chacha20_crypt( const unsigned char key[32],
                              const unsigned char nonce[12],
                              uint32_t counter,
                              size_t size,
                              const unsigned char* input,
                              unsigned char* output );
  
  #if defined(MBEDTLS_SELF_TEST)
  /**
   * \brief           The ChaCha20 checkup routine.
   *
   * \return          \c 0 on success.
   * \return          \c 1 on failure.
   */
  int mbedtls_chacha20_self_test( int verbose );
  #endif /* MBEDTLS_SELF_TEST */
  
  #ifdef __cplusplus
  }
  #endif
  
  #endif /* MBEDTLS_CHACHA20_H */
  