cuberite/polarssl
1
0
Fork 0
mirror of https://github.com/cuberite/polarssl.git synced 2025-11-04 04:32:24 -05:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation to match new guidelines.

Browse Source
This commit is contained in:
Manuel Pégourié-Gonnard 2018-05-08 12:43:48 +02:00
parent fe725defae
commit b500f8b911
4 changed files with 350 additions and 234 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
include/mbedtls/chacha20.h
View File

@ -1,11 +1,18 @@
/**
* \file chacha20.h
*
* \brief ChaCha20 cipher.
* \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-2016, ARM Limited, All Rights Reserved
*/
/* 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
@ -20,8 +27,9 @@
* 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)
* This file is part of Mbed TLS (https://tls.mbed.org)
*/
#ifndef MBEDTLS_CHACHA20_H
#define MBEDTLS_CHACHA20_H
@ -44,10 +52,10 @@ extern "C" {
typedef struct
{
uint32_t initial_state[16]; /*! Holds the initial state (before round operations) */
uint32_t working_state[16]; /*! Holds the working state (after round operations) */
uint8_t keystream8[64]; /*! Holds leftover keystream bytes */
size_t keystream_bytes_used; /*! Number of keystream bytes currently used */
uint32_t initial_state[16]; /*! The initial state (before round operations). */
uint32_t working_state[16]; /*! The working state (after round operations). */
uint8_t keystream8[64]; /*! Leftover keystream bytes. */
size_t keystream_bytes_used; /*! Number of keystream bytes already used. */
}
mbedtls_chacha20_context;
@ -56,118 +64,141 @@ mbedtls_chacha20_context;
#endif /* MBEDTLS_CHACHA20_ALT */
/**
* \brief Initialize ChaCha20 context
* \brief This function initializes the specified ChaCha20 context.
*
* \param ctx ChaCha20 context to be initialized
* 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.
*/
void mbedtls_chacha20_init( mbedtls_chacha20_context *ctx );
/**
* \brief Clear ChaCha20 context
* \brief This function releases and clears the specified ChaCha20 context.
*
* \param ctx ChaCha20 context to be cleared
* \param ctx The ChaCha20 context to clear.
*/
void mbedtls_chacha20_free( mbedtls_chacha20_context *ctx );
/**
* \brief Set the ChaCha20 key.
* \brief This function sets the encryption/decryption key.
*
* \note The nonce and counter must be set after calling this function,
* before data can be encrypted/decrypted. The nonce and
* counter are set by calling mbedtls_chacha20_starts.
* \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().
*
* \see mbedtls_chacha20_starts
* \param ctx The ChaCha20 context to which the key should be bound.
* \param key The encryption/decryption key. Must be 32 bytes in length.
*
* \param ctx The context to setup.
* \param key Buffer containing the 256-bit key. Must be 32 bytes in length.
*
* \return MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA is returned if ctx or key
* is NULL, or if key_bits is not 128 or 256.
* Otherwise, 0 is returned to indicate success.
* \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 Set the ChaCha20 nonce and initial counter value.
* \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 and/or initial
* counter value.
* calling this function to change the nonce.
*
* \param ctx The ChaCha20 context.
* \param nonce Buffer containing the 96-bit nonce. Must be 12 bytes in size.
* \param counter Initial counter value to use. This is usually 0.
* \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.
*
* \return MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA is returned if ctx or
* nonce is NULL.
* Otherwise, 0 is returned to indicate success.
* \param ctx The ChaCha20 context to which the nonce should be bound.
* \param nonce The nonce. Must be 12 bytes in size.
* \param counter The initial counter value. This is usually 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 Encrypt or decrypt data.
* \brief This function encrypts or decrypts data.
*
* This function is used to both encrypt and decrypt 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 mbedtls_chacha20_setkey and mbedtls_chacha20_starts must be
* called at least once to setup the context before this function
* can be called.
* \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.
*
* \param ctx The ChaCha20 context.
* \param size The length (in bytes) to process. This can have any length.
* \param input Buffer containing the input data.
* \note This function can be called mutliple 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.
* \param size The length of the input data in bytes.
* \param input The buffer holding the input data.
* This pointer can be NULL if size == 0.
* \param output Buffer containing the output data.
* \param output The buffer holding the output data.
* Must be able to hold \p size bytes.
* This pointer can be NULL if size == 0.
*
* \return MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if the ctx, input, or
* \return \c 0 on success.
* \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if the ctx, input, or
* output pointers are NULL.
* Otherwise, 0 is returned to indicate success.
*/
int mbedtls_chacha20_update( mbedtls_chacha20_context *ctx,
size_t size,
const unsigned char *input,
unsigned char *output );
size_t size,
const unsigned char *input,
unsigned char *output );
/**
* \brief Encrypt or decrypt a message using ChaCha20.
* \brief This function encrypts or decrypts data with ChaCha20 and
* the given key and nonce.
*
* This function is used the same way for encrypting and
* decrypting data. It's not necessary to specify which
* operation is being performed.
* Since ChaCha20 is a stream cipher, the same operation is
* used for encrypting and decrypting data.
*
* \note The \p input and \p output buffers may overlap, but only
* if input >= output (i.e. only if input points ahead of
* the output pointer).
* \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.
*
* \param key Buffer containing the 256-bit key. Must be 32 bytes in length.
* \param nonce Buffer containing the 96-bit nonce. Must be 12 bytes in length.
* \note The \p input and \p output pointers must either be equal or
* point to non-overlapping buffers.
*
* \param key The encryption/decryption key. Must be 32 bytes in length.
* \param nonce The nonce. Must be 12 bytes in size.
* \param counter The initial counter value. This is usually 0.
* \param data_len The number of bytes to process.
* \param input Buffer containing the input data (data to encrypt or decrypt).
* \param output Buffer to where the processed data is written.
* \param size The length of the input data in bytes.
* \param input The buffer holding the input data.
* This pointer can be NULL if size == 0.
* \param output The buffer holding the output data.
* Must be able to hold \p size bytes.
* This pointer can be NULL if size == 0.
*
* \return MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if key, nonce, input,
* \return \c 0 on success.
* \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if key, nonce, input,
* or output is NULL.
* Otherwise, 0 is returned to indicate success.
*/
int mbedtls_chacha20_crypt( const unsigned char key[32],
const unsigned char nonce[12],
uint32_t counter,
size_t data_len,
size_t size,
const unsigned char* input,
unsigned char* output );
/**
* \brief Checkup routine
* \brief The ChaCha20 checkup routine.
*
* \return 0 if successful, or 1 if the test failed
* \return \c 0 on success.
* \return \c 1 on failure.
*/
int mbedtls_chacha20_self_test( int verbose );

297
include/mbedtls/chachapoly.h
View File

@ -1,9 +1,18 @@
/**
* \file chachapoly.h
*
* \brief ChaCha20-Poly1305 AEAD construction based on RFC 7539.
* \brief This file contains the AEAD-ChaCha20-Poly1305 definitions and
* functions.
*
* Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
* ChaCha20-Poly1305 is an algorithm for Authenticated Encryption
* with Associated Data (AEAD) that can be used to encrypt and
* authenticate data. It is based on ChaCha20 and Poly1305 by Daniel
* Bernstein and was 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
@ -18,8 +27,9 @@
* 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)
* This file is part of Mbed TLS (https://tls.mbed.org)
*/
#ifndef MBEDTLS_CHACHAPOLY_H
#define MBEDTLS_CHACHAPOLY_H
@ -30,7 +40,7 @@
#endif
#define MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA -0x00047 /**< Invalid input parameter(s). */
#define MBEDTLS_ERR_CHACHAPOLY_BAD_STATE -0x00049 /**< The requested operation is not permitted in the current state */
#define MBEDTLS_ERR_CHACHAPOLY_BAD_STATE -0x00049 /**< The requested operation is not permitted in the current state. */
#define MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED -0x00049 /**< Authenticated decryption failed: data was not authentic. */
@ -40,8 +50,8 @@ extern "C" {
typedef enum
{
MBEDTLS_CHACHAPOLY_ENCRYPT,
MBEDTLS_CHACHAPOLY_DECRYPT
MBEDTLS_CHACHAPOLY_ENCRYPT, /**< The mode value for performing encryption. */
MBEDTLS_CHACHAPOLY_DECRYPT /**< The mode value for performing decryption. */
}
mbedtls_chachapoly_mode_t;
@ -52,12 +62,12 @@ mbedtls_chachapoly_mode_t;
typedef struct
{
mbedtls_chacha20_context chacha20_ctx; /** ChaCha20 context */
mbedtls_poly1305_context poly1305_ctx; /** Poly1305 context */
uint64_t aad_len; /** Length (bytes) of the Additional Authenticated Data */
uint64_t ciphertext_len; /** Length (bytes) of the ciphertext */
int state; /** Current state of the context */
mbedtls_chachapoly_mode_t mode; /** Cipher mode (encrypt or decrypt) */
mbedtls_chacha20_context chacha20_ctx; /**< The ChaCha20 context. */
mbedtls_poly1305_context poly1305_ctx; /**< The Poly1305 context. */
uint64_t aad_len; /**< The length (bytes) of the Additional Authenticated Data. */
uint64_t ciphertext_len; /**< The length (bytes) of the ciphertext. */
int state; /**< The current state of the context. */
mbedtls_chachapoly_mode_t mode; /**< Cipher mode (encrypt or decrypt). */
}
mbedtls_chachapoly_context;
@ -66,112 +76,144 @@ mbedtls_chachapoly_context;
#endif /* !MBEDTLS_CHACHAPOLY_ALT */
/**
* \brief Initialize ChaCha20-Poly1305 context
* \brief This function initializes the specified ChaCha20-Poly1305 context.
*
* \param ctx ChaCha20-Poly1305 context to be initialized
* It must be the first API called before using
* the context. It must be followed by a call to
* \c mbedtls_chachapoly_setkey() before any operation can be
* done, and to \c mbedtls_chachapoly_free() once all
* operations with that context have been finished.
*
* In order to encrypt or decrypt full messages at once, for
* each message you should make a single call to
* \c mbedtls_chachapoly_crypt_and_tag() or
* \c mbedtls_chachapoly_auth_decrypt().
*
* In order to encrypt or decrypt messages piecewise, for each
* message you should make a call to
* \c mbedtls_chachapoly_starts(), then 0 or more calls to
* \c mbedtls_chachapoly_update_aad(), then 0 or more calls to
* \c mbedtls_chachapoly_update(), then one call to
* \c mbedtls_chachapoly_finish().
*
*
* \param ctx The ChachaPoly context to initialize.
*/
void mbedtls_chachapoly_init( mbedtls_chachapoly_context *ctx );
/**
* \brief Clear ChaCha20-Poly1305 context
* \brief This function releases and clears the specified ChaCha20-Poly1305 context.
*
* \param ctx ChaCha20-Poly1305 context to be cleared
* \param ctx The ChachaPoly context to clear.
*/
void mbedtls_chachapoly_free( mbedtls_chachapoly_context *ctx );
/**
* \brief Set the ChaCha20-Poly1305 symmetric encryption key.
* \brief This function sets the ChaCha20-Poly1305 symmetric encryption key.
*
* \param ctx The ChaCha20-Poly1305 context.
* \param key The 256-bit (32 bytes) key.
* \param ctx The ChaCha20-Poly1305 context to which the key should be
* bound.
* \param key The 256-bit (32 bytes) key.
*
* \return MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned
* if \p ctx or \p key are NULL.
* Otherwise, 0 is returned to indicate success.
* \return \c 0 on success.
* \return #MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA
* if \p ctx or \p key are NULL.
*/
int mbedtls_chachapoly_setkey( mbedtls_chachapoly_context *ctx,
const unsigned char key[32] );
/**
* \brief Setup ChaCha20-Poly1305 context for encryption or decryption.
* \brief This function starts a ChaCha20-Poly1305 encryption or
* decryption operation.
*
* \note If the context is being used for AAD only (no data to
* encrypt or decrypt) then \p mode can be set to any value.
* \warning You must never use the same nonce twice with the same key.
* This would void any confidentiality and authenticity
* guarantees for the messages encrypted with the same nonce
* and key.
*
* \param ctx The ChaCha20-Poly1305 context.
* \param nonce The nonce/IV to use for the message. This must be unique
* for every message encrypted under the same key.
* \param mode Specifies whether the context is used to encrypt or
* decrypt data.
* \note If the context is being used for AAD only (no data to
* encrypt or decrypt) then \p mode can be set to any value.
*
* \return MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned
* if \p ctx or \p mac are NULL.
* Otherwise, 0 is returned to indicate success.
* \param ctx The ChaCha20-Poly1305 context.
* \param nonce The nonce/IV to use for the message. Must be 12 bytes.
* \param mode The operation to perform: #MBEDTLS_CHACHAPOLY_ENCRYPT or
* #MBEDTLS_CHACHAPOLY_DECRYPT.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA
* if \p ctx or \p mac are NULL.
*/
int mbedtls_chachapoly_starts( mbedtls_chachapoly_context *ctx,
const unsigned char nonce[12],
mbedtls_chachapoly_mode_t mode );
/**
* \brief Process additional authenticated data (AAD).
* \brief This function feeds additional data to be authenticated
* into an ongoing ChaCha20-Poly1305 operation.
*
* This function processes data that is authenticated, but
* not encrypted.
* The Additional Authenticated Data (AAD), also called
* Associated Data (AD) is only authenticated but not
* encrypted nor included in the encrypted output. It is
* usually transmitted separately fro mthe ciphertext or
* computed locally by each party.
*
* \note This function is called before data is encrypted/decrypted.
* I.e. call this function to process the AAD before calling
* mbedtls_chachapoly_update.
* \note This function is called before data is encrypted/decrypted.
* I.e. call this function to process the AAD before calling
* \c mbedtls_chachapoly_update().
*
* You may call this function multiple times to process
* an arbitrary amount of AAD. It is permitted to call
* this function 0 times, if no AAD is used.
* You may call this function multiple times to process
* an arbitrary amount of AAD. It is permitted to call
* this function 0 times, if no AAD is used.
*
* This function cannot be called any more if data has
* been processed by mbedtls_chachapoly_update,
* or if the context has been finished.
* This function cannot be called any more if data has
* been processed by \c mbedtls_chachapoly_update(),
* or if the context has been finished.
*
* \param ctx The ChaCha20-Poly1305 context.
* \param aad_len The length (in bytes) of the AAD. The length has no
* restrictions.
* \param aad Buffer containing the AAD.
* This pointer can be NULL if aad_len == 0.
* \param ctx The ChaCha20-Poly1305 context to use.
* \param aad_len The length (in bytes) of the AAD. The length has no
* restrictions.
* \param aad Buffer containing the AAD.
* This pointer can be NULL if aad_len == 0.
*
* \return MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned
* if \p ctx or \p aad are NULL.
* MBEDTLS_ERR_CHACHAPOLY_BAD_STATE is returned if
* the context has not been setup, the context has been
* finished, or if the AAD has been finished.
* Otherwise, 0 is returned to indicate success.
* \return \c 0 on success.
* \return #MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA
* if \p ctx or \p aad are NULL.
* \return #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
* if the operations has not been started or has been
* finished, or if the AAD has been finished.
*/
int mbedtls_chachapoly_update_aad( mbedtls_chachapoly_context *ctx,
size_t aad_len,
const unsigned char *aad );
/**
* \brief Encrypt/decrypt data.
* \brief Thus function feeds data to be encrypted or decrypted
* into an on-going ChaCha20-Poly1305
* operation.
*
* The direction (encryption or decryption) depends on the
* mode that was given when calling
* mbedtls_chachapoly_starts.
* The direction (encryption or decryption) depends on the
* mode that was given when calling
* \c mbedtls_chachapoly_starts().
*
* You may call this function multiple times to process
* an arbitrary amount of data. It is permitted to call
* this function 0 times, if no data is to be encrypted
* or decrypted.
* You may call this function multiple times to process
* an arbitrary amount of data. It is permitted to call
* this function 0 times, if no data is to be encrypted
* or decrypted.
*
* \param ctx The ChaCha20-Poly1305 context.
* \param len The length (in bytes) of the data to encrypt or decrypt.
* \param input Buffer containing the data to encrypt or decrypt.
* This pointer can be NULL if len == 0.
* \param output Buffer to where the encrypted or decrypted data is written.
* This pointer can be NULL if len == 0.
* \param ctx The ChaCha20-Poly1305 context to use.
* \param len The length (in bytes) of the data to encrypt or decrypt.
* \param input The buffer containing the data to encrypt or decrypt.
* This pointer can be NULL if len == 0.
* \param output The buffer to where the encrypted or decrypted data is written.
* Must be able to hold \p len bytes.
* This pointer can be NULL if len == 0.
*
* \return MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned
* if \p ctx, \p input, or \p output are NULL.
* MBEDTLS_ERR_CHACHAPOLY_BAD_STATE is returned if
* the context has not been setup, or if the context has been
* finished.
* Otherwise, 0 is returned to indicate success.
* \return \c 0 on success.
* \return #MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA
* if \p ctx, \p input, or \p output are NULL.
* \return #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
* if the operation has not been started or has been
* finished.
*/
int mbedtls_chachapoly_update( mbedtls_chachapoly_context *ctx,
size_t len,
@ -179,42 +221,51 @@ int mbedtls_chachapoly_update( mbedtls_chachapoly_context *ctx,
unsigned char *output );
/**
* \brief Compute the ChaCha20-Poly1305 MAC.
* \brief This function finished the ChaCha20-Poly1305 operation and
* generates the MAC (authentication tag).
*
* \param ctx The ChaCha20-Poly1305 context.
* \param mac Buffer to where the 128-bit (16 bytes) MAC is written.
* \param ctx The ChaCha20-Poly1305 context to use.
* \param mac The buffer to where the 128-bit (16 bytes) MAC is written.
*
* \return MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned
* if \p ctx or \p mac are NULL.
* MBEDTLS_ERR_CHACHAPOLY_BAD_STATE is returned if
* the context has not been setup.
* Otherwise, 0 is returned to indicate success.
* \return \c 0 on success.
* \return #MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA
* if \p ctx or \p mac are NULL.
* \return #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
* if the operation has not been started or has been
* finished.
*/
int mbedtls_chachapoly_finish( mbedtls_chachapoly_context *ctx,
unsigned char mac[16] );
/**
* \brief Encrypt or decrypt data, and produce a MAC (tag) with ChaCha20-Poly1305.
* \brief This function performs a complete ChaCha20-Poly1305
* operation with the previously-set key.
*
* \param ctx The ChachaPoly context.
* \param mode Specifies whether the data in the \p input buffer is to
* be encrypted or decrypted. If there is no data to encrypt
* or decrypt (i.e. \p ilen is 0) then the value of this
* parameter does not matter.
* \param length The length (in bytes) of the data to encrypt or decrypt.
* \param nonce The 96-bit (12 bytes) nonce/IV to use.
* \param aad Buffer containing the additional authenticated data (AAD).
* This pointer can be NULL if aad_len == 0.
* \param aad_len The length (in bytes) of the AAD data to process.
* \param input Buffer containing the data to encrypt or decrypt.
* This pointer can be NULL if ilen == 0.
* \param output Buffer to where the encrypted or decrypted data is written.
* This pointer can be NULL if ilen == 0.
* \param tag Buffer to where the computed 128-bit (16 bytes) MAC is written.
* \note Before using this function, you must set the key with
* \c mbedtls_chachapoly_setkey().
*
* \return MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned
* if one or more of the required parameters are NULL.
* Otherwise, 0 is returned to indicate success.
* \warning You must never use the same nonce twice with the same key.
* This would void any confidentiality and authenticity
* guarantees for the messages encrypted with the same nonce
* and key.
*
* \param ctx The ChaCha20-Poly1305 context to use (holds the key).
* \param mode The operation to perform: #MBEDTLS_CHACHAPOLY_ENCRYPT or
* #MBEDTLS_CHACHAPOLY_DECRYPT.
* \param length The length (in bytes) of the data to encrypt or decrypt.
* \param nonce The 96-bit (12 bytes) nonce/IV to use.
* \param aad The buffer containing the additional authenticated data (AAD).
* This pointer can be NULL if aad_len == 0.
* \param aad_len The length (in bytes) of the AAD data to process.
* \param input The buffer containing the data to encrypt or decrypt.
* This pointer can be NULL if ilen == 0.
* \param output The buffer to where the encrypted or decrypted data is written.
* This pointer can be NULL if ilen == 0.
* \param tag The buffer to where the computed 128-bit (16 bytes) MAC is written.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA
* if one or more of the required parameters are NULL.
*/
int mbedtls_chachapoly_crypt_and_tag( mbedtls_chachapoly_context *ctx,
mbedtls_chachapoly_mode_t mode,
@ -227,22 +278,29 @@ int mbedtls_chachapoly_crypt_and_tag( mbedtls_chachapoly_context *ctx,
unsigned char tag[16] );
/**
* \brief Decrypt data and check a MAC (tag) with ChaCha20-Poly1305.
* \brief This function performs a complete ChaCha20-Poly1305
* authenticated decryption with the previously-set key.
*
* \param ctx The ChachaPoly context.
* \param length The length of the input and output data.
* \param nonce The nonce / initialization vector.
* \param aad The buffer holding the additional authenticated data.
* \param aad_len The length of the additional authenticated data.
* \param tag The buffer holding the tag.
* \param input The buffer holding the input data.
* \param output The buffer for holding the output data.
* \note Before using this function, you must set the key with
* \c mbedtls_chachapoly_setkey().
*
* \return MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned
* if one or more of the required parameters are NULL.
* MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED if the tag does not
* match.
* Otherwise, 0 is returned to indicate success.
* \param ctx The ChaCha20-Poly1305 context to use (holds the key).
* \param length The length (in bytes) of the data to decrypt.
* \param nonce The 96-bit (12 bytes) nonce/IV to use.
* \param aad The buffer containing the additional authenticated data (AAD).
* This pointer can be NULL if aad_len == 0.
* \param aad_len The length (in bytes) of the AAD data to process.
* \param tag The buffer holding the authentication tag.
* \param input The buffer containing the data to decrypt.
* This pointer can be NULL if ilen == 0.
* \param output The buffer to where the decrypted data is written.
* This pointer can be NULL if ilen == 0.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA
* if one or more of the required parameters are NULL.
* \return #MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED
* if the data was not authentic.
*/
int mbedtls_chachapoly_auth_decrypt( mbedtls_chachapoly_context *ctx,
size_t length,
@ -254,9 +312,10 @@ int mbedtls_chachapoly_auth_decrypt( mbedtls_chachapoly_context *ctx,
unsigned char *output );
/**
* \brief Checkup routine
* \brief The ChaCha20-Poly1305 checkup routine.
*
* \return 0 if successful, or 1 if the test failed
* \return \c 0 on success.
* \return \c 1 on failure.
*/
int mbedtls_chachapoly_self_test( int verbose );

6
include/mbedtls/cipher.h
View File

@ -86,7 +86,7 @@ typedef enum {
MBEDTLS_CIPHER_ID_CAMELLIA, /**< The Camellia cipher. */
MBEDTLS_CIPHER_ID_BLOWFISH, /**< The Blowfish cipher. */
MBEDTLS_CIPHER_ID_ARC4, /**< The RC4 cipher. */
MBEDTLS_CIPHER_ID_CHACHA20, /**< The Chacha20 cipher. */
MBEDTLS_CIPHER_ID_CHACHA20, /**< The ChaCha20 cipher. */
} mbedtls_cipher_id_t;
/**
@ -146,8 +146,8 @@ typedef enum {
MBEDTLS_CIPHER_CAMELLIA_128_CCM, /**< Camellia cipher with 128-bit CCM mode. */
MBEDTLS_CIPHER_CAMELLIA_192_CCM, /**< Camellia cipher with 192-bit CCM mode. */
MBEDTLS_CIPHER_CAMELLIA_256_CCM, /**< Camellia cipher with 256-bit CCM mode. */
MBEDTLS_CIPHER_CHACHA20, /**< Chacha20 stream cipher. */
MBEDTLS_CIPHER_CHACHA20_POLY1305, /**< Chacha20-Poly1305 AEAD cipher. */
MBEDTLS_CIPHER_CHACHA20, /**< ChaCha20 stream cipher. */
MBEDTLS_CIPHER_CHACHA20_POLY1305, /**< ChaCha20-Poly1305 AEAD cipher. */
} mbedtls_cipher_type_t;
/** Supported cipher modes. */

124
include/mbedtls/poly1305.h
View File

@ -1,9 +1,18 @@
/**
* \file poly1305.h
*
* \brief Poly1305 authenticator algorithm.
* \brief This file containts Poly1305 definitions and functions.
*
* Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
* Poly1305 is a one-time message authenticator that can be used to
* authenticate messages. Poly1305-AES was created by Daniel
* Bernstein https://cr.yp.to/mac/poly1305-20050329.pdf The generic
* Poly1305 algorithm (not tied to AES) 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
@ -18,8 +27,9 @@
* 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)
* This file is part of Mbed TLS (https://tls.mbed.org)
*/
#ifndef MBEDTLS_POLY1305_H
#define MBEDTLS_POLY1305_H
@ -42,11 +52,11 @@ extern "C" {
typedef struct
{
uint32_t r[4]; /** Stores the value for 'r' (low 128 bits of the key) */
uint32_t s[4]; /** Stores the value for 's' (high 128 bits of the key) */
uint32_t acc[5]; /** Accumulator number */
uint8_t queue[16]; /** Stores partial block data */
size_t queue_len; /** Number of bytes stored in 'queue'. Always less than 16 */
uint32_t r[4]; /** The value for 'r' (low 128 bits of the key). */
uint32_t s[4]; /** The value for 's' (high 128 bits of the key). */
uint32_t acc[5]; /** The accumulator number. */
uint8_t queue[16]; /** The current partial block of data. */
size_t queue_len; /** The number of bytes stored in 'queue'. */
}
mbedtls_poly1305_context;
@ -55,82 +65,97 @@ mbedtls_poly1305_context;
#endif /* MBEDTLS_POLY1305_ALT */
/**
* \brief Initialize a Poly1305 context
* \brief This function initializes the specified Poly1305 context.
*
* \param ctx The Poly1305 context to be initialized
* It must be the first API called before using
* the context.
*
* It is usually followed by a call to
* \c mbedtls_poly1305_starts(), then one or more calls to
* \c mbedtls_poly1305_update(), then one call to
* \c mbedtls_poly1305_finish(), then finally
* \c mbedtls_poly1305_free().
*
* \param ctx The Poly1305 context to initialize.
*/
void mbedtls_poly1305_init( mbedtls_poly1305_context *ctx );
/**
* \brief Clear a Poly1305 context
* \brief This function releases and clears the specified Poly1305 context.
*
* \param ctx The Poly1305 context to be cleared
* \param ctx The Poly1305 context to clear.
*/
void mbedtls_poly1305_free( mbedtls_poly1305_context *ctx );
/**
* \brief Set the Poly1305 authentication key.
* \brief This function sets the one-time authentication key.
*
* \warning The key should be unique, and \b MUST be
* unpredictable for each invocation of Poly1305.
* \warning The key must be unique and unpredictable for each
* invocation of Poly1305.
*
* \param ctx The Poly1305 context.
* \param key Buffer containing the 256-bit key.
* \param ctx The Poly1305 context to which the key should be bound.
* \param key The buffer containing the 256-bit key.
*
* \return MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA is returned if ctx
* or key are NULL.
* Otherwise, 0 is returned to indicate success.
* \return \c 0 on success.
* \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
* if ctx or key are NULL.
*/
int mbedtls_poly1305_starts( mbedtls_poly1305_context *ctx,
const unsigned char key[32] );
/**
* \brief Process data with Poly1305.
* \brief This functions feeds an input bufer into an ongoing
* Poly1305 computation.
*
* This function can be called multiple times to process
* a stream of data.
* It is called between \c mbedtls_cipher_cmac_starts() and
* \c mbedtls_cipher_cmac_finish().
* Can be called repeatedly to process a stream of data.
*
* \param ctx The Poly1305 context.
* \param ilen The input length (in bytes). Any value is accepted.
* \param input Buffer containing the input data to Process.
* This pointer can be NULL if ilen == 0.
* \param ctx The Poly1305 context to use for the Poly1305 operation.
* \param ilen The length of the input data (in bytes). Any value is accepted.
* \param input The buffer holding the input data.
* This pointer can be NULL if ilen == 0.
*
* \return MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA is returned if ctx
* or input are NULL.
* Otherwise, 0 is returned to indicate success.
* \return \c 0 on success.
* \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
* if ctx or input are NULL.
*/
int mbedtls_poly1305_update( mbedtls_poly1305_context *ctx,
size_t ilen,
const unsigned char *input );
/**
* \brief Generate the Poly1305 MAC.
* \brief This function generates the Poly1305 Message
* Authentication Code (MAC).
*
* \param ctx The Poly1305 context.
* \param mac Buffer to where the MAC is written. Must be big enough
* to hold the 16-byte MAC.
* \param ctx The Poly1305 context to use for the Poly1305 operation.
* \param mac The buffer to where the MAC is written. Must be big enough
* to hold the 16-byte MAC.
*
* \return MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA is returned if ctx
* or mac are NULL.
* Otherwise, 0 is returned to indicate success.
* \return \c 0 on success.
* \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
* if ctx or mac are NULL.
*/
int mbedtls_poly1305_finish( mbedtls_poly1305_context *ctx,
unsigned char mac[16] );
/**
* \brief Generate the Poly1305 MAC of some data with the given key.
* \brief This function calculates the Poly1305 MAC of the input
* buffer with the provided key.
*
* \warning The key should be unique, and \b MUST be
* unpredictable for each invocation of Poly1305.
* \warning The key must be unique and unpredictable for each
* invocation of Poly1305.
*
* \param key Buffer containing the 256-bit (32 bytes) key.
* \param ilen The length of the input data (in bytes).
* \param input Buffer containing the input data to process.
* \param mac Buffer to where the 128-bit (16 bytes) MAC is written.
* \param key The buffer containing the 256-bit key.
* \param ilen The length of the input data (in bytes). Any value is accepted.
* \param input The buffer holding the input data.
* This pointer can be NULL if ilen == 0.
* \param mac The buffer to where the MAC is written. Must be big enough
* to hold the 16-byte MAC.
*
* \return MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA is returned if key,
* input, or mac are NULL.
* Otherwise, 0 is returned to indicate success.
* \return \c 0 on success.
* \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
* if key, input, or mac are NULL.
*/
int mbedtls_poly1305_mac( const unsigned char key[32],
size_t ilen,
@ -138,9 +163,10 @@ int mbedtls_poly1305_mac( const unsigned char key[32],
unsigned char mac[16] );
/**
* \brief Checkup routine
* \brief The Poly1305 checkup routine.
*
* \return 0 if successful, or 1 if the test failed
* \return \c 0 on success.
* \return \c 1 on failure.
*/
int mbedtls_poly1305_self_test( int verbose );