cuberite/polarssl
1
0
Fork 0
mirror of https://github.com/cuberite/polarssl.git synced 2025-10-31 03:30:35 -04:00
Code Issues Packages Projects Releases Wiki Activity

Improve GCM documentation

Browse Source 
- Rephrase file/function/parameter/enum/define/error descriptions into
  full and clear sentences.
- Make sure to adhere to the Arm writing guidelines.
- Fix missing/incorrect Doxygen tags.
- Standardize terminology used within the file.

GitHub PR: #1324
This commit is contained in:
Rose Zadik 2018-01-26 10:56:42 +00:00 committed by Jaeden Amero
parent 41ad082484
commit 17b4f7fc60
1 changed files with 110 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

194
include/mbedtls/gcm.h
View File

@ -1,10 +1,16 @@
/** /**
* \file gcm.h * \file gcm.h
* *
* \brief Galois/Counter mode for 128-bit block ciphers * \brief Galois/Counter Mode (GCM) for 128-bit block ciphers, as defined
* in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
* (GCM), Natl. Inst. Stand. Technol.</em>
*
* For more information on GCM, see <em>NIST SP 800-38D: Recommendation for
* Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</em>.
*
*/ */
/* /*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
* Licensed under the Apache License, Version 2.0 (the "License"); you may * Licensed under the Apache License, Version 2.0 (the "License"); you may
@ -19,8 +25,9 @@
* See the License for the specific language governing permissions and * See the License for the specific language governing permissions and
* limitations under the License. * 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_GCM_H #ifndef MBEDTLS_GCM_H
#define MBEDTLS_GCM_H #define MBEDTLS_GCM_H
@ -42,39 +49,49 @@ extern "C" {
#endif #endif
/** /**
* \brief GCM context structure * \brief The GCM context structure.
*/ */
typedef struct { typedef struct {
mbedtls_cipher_context_t cipher_ctx;/*!< cipher context used */ mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */
uint64_t HL[16]; /*!< Precalculated HTable */ uint64_t HL[16]; /*!< Precalculated HTable low. */
uint64_t HH[16]; /*!< Precalculated HTable */ uint64_t HH[16]; /*!< Precalculated HTable high. */
uint64_t len; /*!< Total data length */ uint64_t len; /*!< The total length of the encrypted data. */
uint64_t add_len; /*!< Total add length */ uint64_t add_len; /*!< The total length of the additional data. */
unsigned char base_ectr[16];/*!< First ECTR for tag */ unsigned char base_ectr[16]; /*!< The first ECTR for tag. */
unsigned char y[16]; /*!< Y working value */ unsigned char y[16]; /*!< The Y working value. */
unsigned char buf[16]; /*!< buf working value */ unsigned char buf[16]; /*!< The buf working value. */
int mode; /*!< Encrypt or Decrypt */ int mode; /*!< The operation to perform:
#MBEDTLS_GCM_ENCRYPT or
#MBEDTLS_GCM_DECRYPT. */
} }
mbedtls_gcm_context; mbedtls_gcm_context;
/** /**
* \brief Initialize GCM context (just makes references valid) * \brief This function initializes the specified GCM context,
* Makes the context ready for mbedtls_gcm_setkey() or * to make references valid, and prepares the context
* mbedtls_gcm_free(). * for mbedtls_gcm_setkey() or mbedtls_gcm_free().
* *
* \param ctx GCM context to initialize * The function does not bind the GCM context to a particular
* cipher, nor set the key. For this purpose, use
* mbedtls_gcm_setkey().
*
* \param ctx The GCM context to initialize.
*/ */
void mbedtls_gcm_init( mbedtls_gcm_context *ctx ); void mbedtls_gcm_init( mbedtls_gcm_context *ctx );
/** /**
* \brief GCM initialization (encryption) * \brief This function associates a GCM context with a
* cipher algorithm and a key.
* *
* \param ctx GCM context to be initialized * \param ctx The GCM context to initialize.
* \param cipher cipher to use (a 128-bit block cipher) * \param cipher The 128-bit block cipher to use.
* \param key encryption key * \param key The encryption key.
* \param keybits must be 128, 192 or 256 * \param keybits The key size in bits. Valid options are:
* <ul><li>128 bits</li>
* <li>192 bits</li>
* <li>256 bits</li></ul>
* *
* \return 0 if successful, or a cipher specific error code * \return \c 0 on success, or a cipher specific error code.
*/ */
int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx, int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
mbedtls_cipher_id_t cipher, mbedtls_cipher_id_t cipher,
@ -82,26 +99,27 @@ int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
unsigned int keybits ); unsigned int keybits );
/** /**
* \brief GCM buffer encryption/decryption using a block cipher * \brief This function performs GCM encryption or decryption of a buffer.
* *
* \note On encryption, the output buffer can be the same as the input buffer. * \note For encryption, the output buffer can be the same as the input buffer.
* On decryption, the output buffer cannot be the same as input buffer. * For decryption, the output buffer cannot be the same as input buffer.
* If buffers overlap, the output buffer must trail at least 8 bytes * If the buffers overlap, the output buffer must trail at least 8 Bytes
* behind the input buffer. * behind the input buffer.
* *
* \param ctx GCM context * \param ctx The GCM context to use for encryption or decryption.
* \param mode MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT * \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or
* \param length length of the input data * #MBEDTLS_GCM_DECRYPT.
* \param iv initialization vector * \param length The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
* \param iv_len length of IV * \param iv The initialization vector.
* \param add additional data * \param iv_len The length of the IV.
* \param add_len length of additional data * \param add The buffer holding the additional data.
* \param input buffer holding the input data * \param add_len The length of the additional data.
* \param output buffer for holding the output data * \param input The buffer holding the input data.
* \param tag_len length of the tag to generate * \param output The buffer for holding the output data.
* \param tag buffer for holding the tag * \param tag_len The length of the tag to generate.
* \param tag The buffer for holding the tag.
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx, int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
int mode, int mode,
@ -116,25 +134,26 @@ int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
unsigned char *tag ); unsigned char *tag );
/** /**
* \brief GCM buffer authenticated decryption using a block cipher * \brief This function performs a GCM authenticated decryption of a
* buffer.
* *
* \note On decryption, the output buffer cannot be the same as input buffer. * \note For decryption, the output buffer cannot be the same as input buffer.
* If buffers overlap, the output buffer must trail at least 8 bytes * If the buffers overlap, the output buffer must trail at least 8 Bytes
* behind the input buffer. * behind the input buffer.
* *
* \param ctx GCM context * \param ctx The GCM context.
* \param length length of the input data * \param length The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
* \param iv initialization vector * \param iv The initialization vector.
* \param iv_len length of IV * \param iv_len The length of the IV.
* \param add additional data * \param add The buffer holding the additional data.
* \param add_len length of additional data * \param add_len The length of the additional data.
* \param tag buffer holding the tag * \param tag The buffer holding the tag.
* \param tag_len length of the tag * \param tag_len The length of the tag.
* \param input buffer holding the input data * \param input The buffer holding the input data.
* \param output buffer for holding the output data * \param output The buffer for holding the output data.
* *
* \return 0 if successful and authenticated, * \return 0 if successful and authenticated, or
* MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match * #MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match.
*/ */
int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx, int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
size_t length, size_t length,
@ -148,16 +167,18 @@ int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
unsigned char *output ); unsigned char *output );
/** /**
* \brief Generic GCM stream start function * \brief This function starts a GCM encryption or decryption
* operation.
* *
* \param ctx GCM context * \param ctx The GCM context.
* \param mode MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT * \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or
* \param iv initialization vector * #MBEDTLS_GCM_DECRYPT.
* \param iv_len length of IV * \param iv The initialization vector.
* \param add additional data (or NULL if length is 0) * \param iv_len The length of the IV.
* \param add_len length of additional data * \param add The buffer holding the additional data, or NULL if \p add_len is 0.
* \param add_len The length of the additional data. If 0, \p add is NULL.
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_gcm_starts( mbedtls_gcm_context *ctx, int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
int mode, int mode,
@ -167,21 +188,23 @@ int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
size_t add_len ); size_t add_len );
/** /**
* \brief Generic GCM update function. Encrypts/decrypts using the * \brief This function feeds an input buffer into an ongoing GCM
* given GCM context. Expects input to be a multiple of 16 * encryption or decryption operation.
* bytes! Only the last call before mbedtls_gcm_finish() can be less
* than 16 bytes!
* *
* \note On decryption, the output buffer cannot be the same as input buffer. * ` The function expects input to be a multiple of 16
* If buffers overlap, the output buffer must trail at least 8 bytes * Bytes. Only the last call before calling
* mbedtls_gcm_finish() can be less than 16 Bytes.
*
* \note For decryption, the output buffer cannot be the same as input buffer.
* If the buffers overlap, the output buffer must trail at least 8 Bytes
* behind the input buffer. * behind the input buffer.
* *
* \param ctx GCM context * \param ctx The GCM context.
* \param length length of the input data * \param length The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
* \param input buffer holding the input data * \param input The buffer holding the input data.
* \param output buffer for holding the output data * \param output The buffer for holding the output data.
* *
* \return 0 if successful or MBEDTLS_ERR_GCM_BAD_INPUT * \return \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
*/ */
int mbedtls_gcm_update( mbedtls_gcm_context *ctx, int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
size_t length, size_t length,
@ -189,24 +212,27 @@ int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
unsigned char *output ); unsigned char *output );
/** /**
* \brief Generic GCM finalisation function. Wraps up the GCM stream * \brief This function finishes the GCM operation and generates
* and generates the tag. The tag can have a maximum length of * the authentication tag.
* 16 bytes.
* *
* \param ctx GCM context * It wraps up the GCM stream, and generates the
* \param tag buffer for holding the tag * tag. The tag can have a maximum length of 16 Bytes.
* \param tag_len length of the tag to generate (must be at least 4)
* *
* \return 0 if successful or MBEDTLS_ERR_GCM_BAD_INPUT * \param ctx The GCM context.
* \param tag The buffer for holding the tag.
* \param tag_len The length of the tag to generate. Must be at least four.
*
* \return \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
*/ */
int mbedtls_gcm_finish( mbedtls_gcm_context *ctx, int mbedtls_gcm_finish( mbedtls_gcm_context *ctx,
unsigned char *tag, unsigned char *tag,
size_t tag_len ); size_t tag_len );
/** /**
* \brief Free a GCM context and underlying cipher sub-context * \brief This function clears a GCM context and the underlying
* cipher sub-context.
* *
* \param ctx GCM context to free * \param ctx The GCM context to clear.
*/ */
void mbedtls_gcm_free( mbedtls_gcm_context *ctx ); void mbedtls_gcm_free( mbedtls_gcm_context *ctx );
@ -223,9 +249,9 @@ extern "C" {
#endif #endif
/** /**
* \brief Checkup routine * \brief The GCM checkup routine.
* *
* \return 0 if successful, or 1 if the test failed * \return \c 0 on success, or \c 1 on failure.
*/ */
int mbedtls_gcm_self_test( int verbose ); int mbedtls_gcm_self_test( int verbose );