From ad54c49e750ddfa8f75059cc9fc06018d3670582 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?=
<manuel.pegourie-gonnard@arm.com>
Date: Thu, 13 Dec 2018 11:15:26 +0100
Subject: [PATCH] Document AES accelerator functions as internal
---
include/mbedtls/aes.h | 4 ++--
include/mbedtls/aesni.h | 46 ++++++++++++++++++++++++++++-----------
include/mbedtls/padlock.h | 34 +++++++++++++++++++----------
3 files changed, 58 insertions(+), 26 deletions(-)
diff --git a/include/mbedtls/aes.h b/include/mbedtls/aes.h
index ae80e9df22..d21427e7d7 100644
--- a/include/mbedtls/aes.h
+++ b/include/mbedtls/aes.h
@@ -628,7 +628,7 @@ int mbedtls_internal_aes_decrypt( mbedtls_aes_context *ctx,
* \brief Deprecated internal AES block encryption function
* without return value.
*
- * \deprecated Superseded by mbedtls_aes_encrypt_ext() in 2.5.0.
+ * \deprecated Superseded by mbedtls_internal_aes_encrypt() in 2.5.0.
*
* \param ctx The AES context to use for encryption.
* \param input Plaintext block.
@@ -642,7 +642,7 @@ MBEDTLS_DEPRECATED void mbedtls_aes_encrypt( mbedtls_aes_context *ctx,
* \brief Deprecated internal AES block decryption function
* without return value.
*
- * \deprecated Superseded by mbedtls_aes_decrypt_ext() in 2.5.0.
+ * \deprecated Superseded by mbedtls_internal_aes_decrypt() in 2.5.0.
*
* \param ctx The AES context to use for decryption.
* \param input Ciphertext block.
diff --git a/include/mbedtls/aesni.h b/include/mbedtls/aesni.h
index 746baa0e17..b490cbebfe 100644
--- a/include/mbedtls/aesni.h
+++ b/include/mbedtls/aesni.h
@@ -2,6 +2,9 @@
* \file aesni.h
*
* \brief AES-NI for hardware AES acceleration on some Intel processors
+ *
+ * \warning These functions are only for internal use by other library
+ * functions; you must not call them directly.
*/
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
@@ -42,7 +45,10 @@ extern "C" {
#endif
/**
- * \brief AES-NI features detection routine
+ * \brief Internal AES-NI features detection routine
+ *
+ * \note This function is only for internal use by other library
+ * functions; you must not call it directly.
*
* \param what The feature to detect
* (MBEDTLS_AESNI_AES or MBEDTLS_AESNI_CLMUL)
@@ -52,7 +58,10 @@ extern "C" {
int mbedtls_aesni_has_support( unsigned int what );
/**
- * \brief AES-NI AES-ECB block en(de)cryption
+ * \brief Internal AES-NI AES-ECB block en(de)cryption
+ *
+ * \note This function is only for internal use by other library
+ * functions; you must not call it directly.
*
* \param ctx AES context
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
@@ -62,12 +71,15 @@ int mbedtls_aesni_has_support( unsigned int what );
* \return 0 on success (cannot fail)
*/
int mbedtls_aesni_crypt_ecb( mbedtls_aes_context *ctx,
- int mode,
- const unsigned char input[16],
- unsigned char output[16] );
+ int mode,
+ const unsigned char input[16],
+ unsigned char output[16] );
/**
- * \brief GCM multiplication: c = a * b in GF(2^128)
+ * \brief Internal GCM multiplication: c = a * b in GF(2^128)
+ *
+ * \note This function is only for internal use by other library
+ * functions; you must not call it directly.
*
* \param c Result
* \param a First operand
@@ -77,21 +89,29 @@ int mbedtls_aesni_crypt_ecb( mbedtls_aes_context *ctx,
* elements of GF(2^128) as per the GCM spec.
*/
void mbedtls_aesni_gcm_mult( unsigned char c[16],
- const unsigned char a[16],
- const unsigned char b[16] );
+ const unsigned char a[16],
+ const unsigned char b[16] );
/**
- * \brief Compute decryption round keys from encryption round keys
+ * \brief Internal round key inversion.
+ * Compute decryption round keys from encryption round keys
+ *
+ * \note This function is only for internal use by other library
+ * functions; you must not call it directly.
*
* \param invkey Round keys for the equivalent inverse cipher
* \param fwdkey Original round keys (for encryption)
* \param nr Number of rounds (that is, number of round keys minus one)
*/
void mbedtls_aesni_inverse_key( unsigned char *invkey,
- const unsigned char *fwdkey, int nr );
+ const unsigned char *fwdkey,
+ int nr );
/**
- * \brief Perform key expansion (for encryption)
+ * \brief Internal key expansion (for encryption)
+ *
+ * \note This function is only for internal use by other library
+ * functions; you must not call it directly.
*
* \param rk Destination buffer where the round keys are written
* \param key Encryption key
@@ -100,8 +120,8 @@ void mbedtls_aesni_inverse_key( unsigned char *invkey,
* \return 0 if successful, or MBEDTLS_ERR_AES_INVALID_KEY_LENGTH
*/
int mbedtls_aesni_setkey_enc( unsigned char *rk,
- const unsigned char *key,
- size_t bits );
+ const unsigned char *key,
+ size_t bits );
#ifdef __cplusplus
}
diff --git a/include/mbedtls/padlock.h b/include/mbedtls/padlock.h
index 677936ebf8..95e2bfce1d 100644
--- a/include/mbedtls/padlock.h
+++ b/include/mbedtls/padlock.h
@@ -3,6 +3,9 @@
*
* \brief VIA PadLock ACE for HW encryption/decryption supported by some
* processors
+ *
+ * \warning These functions are only for internal use by other library
+ * functions; you must not call them directly.
*/
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
@@ -57,7 +60,10 @@ extern "C" {
#endif
/**
- * \brief PadLock detection routine
+ * \brief Internal PadLock detection routine
+ *
+ * \note This function is only for internal use by other library
+ * functions; you must not call it directly.
*
* \param feature The feature to detect
*
@@ -66,7 +72,10 @@ extern "C" {
int mbedtls_padlock_has_support( int feature );
/**
- * \brief PadLock AES-ECB block en(de)cryption
+ * \brief Internal PadLock AES-ECB block en(de)cryption
+ *
+ * \note This function is only for internal use by other library
+ * functions; you must not call it directly.
*
* \param ctx AES context
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
@@ -76,12 +85,15 @@ int mbedtls_padlock_has_support( int feature );
* \return 0 if success, 1 if operation failed
*/
int mbedtls_padlock_xcryptecb( mbedtls_aes_context *ctx,
- int mode,
- const unsigned char input[16],
- unsigned char output[16] );
+ int mode,
+ const unsigned char input[16],
+ unsigned char output[16] );
/**
- * \brief PadLock AES-CBC buffer en(de)cryption
+ * \brief Internal PadLock AES-CBC buffer en(de)cryption
+ *
+ * \note This function is only for internal use by other library
+ * functions; you must not call it directly.
*
* \param ctx AES context
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
@@ -93,11 +105,11 @@ int mbedtls_padlock_xcryptecb( mbedtls_aes_context *ctx,
* \return 0 if success, 1 if operation failed
*/
int mbedtls_padlock_xcryptcbc( mbedtls_aes_context *ctx,
- int mode,
- size_t length,
- unsigned char iv[16],
- const unsigned char *input,
- unsigned char *output );
+ int mode,
+ size_t length,
+ unsigned char iv[16],
+ const unsigned char *input,
+ unsigned char *output );
#ifdef __cplusplus
}