Add comments to the HMAC (non-)PSA examples
Also clean up / align the structure on existing examples.
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
diff --git a/programs/psa/hmac_non_psa.c b/programs/psa/hmac_non_psa.c
index c7ced7c..0b4eff5 100644
--- a/programs/psa/hmac_non_psa.c
+++ b/programs/psa/hmac_non_psa.c
@@ -1,8 +1,24 @@
-/*
+/**
+ * MD API multi-part HMAC demonstration.
+ *
+ * This programs computes the HMAC of two messages using the multi-part API.
+ *
* This is a companion to hmac_psa.c, doing the same operations with the
* legacy MD API. The goal is that comparing the two programs will help people
* migrating to the PSA Crypto API.
*
+ * When it comes to multi-part HMAC operations, the `mbedtls_md_context`
+ * serves a dual purpose (1) hold the key, and (2) save progress information
+ * for the current operation. With PSA those roles are held by two disinct
+ * objects: (1) a psa_key_id_t to hold the key, and (2) a psa_operation_t for
+ * multi-part progress.
+ *
+ * This program and its companion hmac_non_psa.c illustrate this by doing the
+ * same sequence of multi-part HMAC computation with both APIs; looking at the
+ * two side by side should make the differences and similarities clear.
+ */
+
+/*
* Copyright The Mbed TLS Contributors
* SPDX-License-Identifier: Apache-2.0
*
@@ -19,22 +35,17 @@
* limitations under the License.
*/
-/*
- * When in comes to multi-part HMAC operations, the `mbedtls_md_context`
- * serves a dual purpose (1) hold the key, and (2) save progress information
- * for the current operation. With PSA those roles are held by two disinct
- * objects: (1) a psa_key_id_t to hold the key, and (2) a psa_operation_t for
- * multi-part progress.
- *
- * This program and its companion hmac_psa.c illustrate this by doing the
- * same sequence of multi-part HMAC computation with both APIs; looking at the
- * two side by side should make the differences and similarities clear.
- */
-
-#include <stdio.h>
-
+/* First include Mbed TLS headers to get the Mbed TLS configuration and
+ * platform definitions that we'll use in this program. Also include
+ * standard C headers for functions we'll use here. */
#include "mbedtls/build_info.h"
+#include "mbedtls/md.h"
+
+#include <stdlib.h>
+#include <stdio.h>
+
+/* If the build options we need are not enabled, compile a placeholder. */
#if !defined(MBEDTLS_MD_C)
int main( void )
{
@@ -43,20 +54,22 @@
}
#else
-#include "mbedtls/md.h"
+/* The real program starts here. */
-/*
- * Dummy inputs for HMAC
- */
+/* Dummy inputs for HMAC */
const unsigned char msg1_part1[] = { 0x01, 0x02 };
const unsigned char msg1_part2[] = { 0x03, 0x04 };
const unsigned char msg2_part1[] = { 0x05, 0x05 };
const unsigned char msg2_part2[] = { 0x06, 0x06 };
+/* Dummy key material - never do this in production!
+ * This example program uses SHA-256, so a 32-byte key makes sense. */
const unsigned char key_bytes[32] = { 0 };
+/* Buffer for the output - using SHA-256, so 32-byte output */
unsigned char out[32];
+/* Print the contents of the output buffer in hex */
void print_out( const char *title )
{
printf( "%s:", title );
@@ -65,13 +78,25 @@
printf( "\n" );
}
-#define CHK( code ) \
- do { \
- ret = code; \
- if( ret != 0 ) \
- goto exit; \
+/* Run an Mbed TLS function and bail out if it fails. */
+#define CHK( expr ) \
+ do \
+ { \
+ ret = ( expr ); \
+ if( ret != 0 ) \
+ { \
+ printf( "Error %d at line %d: %s\n", \
+ ret, \
+ __LINE__, \
+ #expr ); \
+ goto exit; \
+ } \
} while( 0 )
+/*
+ * This function demonstrates computation of the HMAC of two messages using
+ * the multipart API.
+ */
int hmac_demo(void)
{
int ret;
@@ -104,10 +129,12 @@
int main(void)
{
- int ret = hmac_demo();
- if( ret != 0 )
- printf( "ret = %d (-0x%04x)\n", ret, (unsigned) -ret );
+ int ret;
+ CHK( hmac_demo() );
+
+exit:
+ return( ret == 0 ? EXIT_SUCCESS : EXIT_FAILURE );
}
#endif