Change sha512 output type from an array to a pointer

The output parameter of mbedtls_sha512_finish_ret and mbedtls_sha512_ret
now has a pointer type rather than array type. This removes spurious
warnings in some compilers when outputting a SHA-384 hash into a
48-byte buffer.

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

ChangeLog.d/sha512-output-type.txt

@@ -0,0 +1,5 @@
+API changes
+   * The output parameter of mbedtls_sha512_finish_ret and mbedtls_sha512_ret
+     now has a pointer type rather than array type. This removes spurious
+     warnings in some compilers when outputting a SHA-384 hash into a
+     48-byte buffer.

docs/3.0-migration-guide.d/sha512-output-type.md

@@ -0,0 +1,8 @@
+SHA-512 output type change
+--------------------------
+
+The output parameter of `mbedtls_sha512_finish_ret()` and `mbedtls_sha512_ret()` now has a pointer type rather than array type. This makes no difference in terms of C semantics, but removes spurious warnings in some compilers when outputting a SHA-384 hash into a 48-byte buffer.
+
+This makes no difference to a vast majority of applications. If your code takes a pointer to one of these functions, you may need to change the type of the pointer.
+
+Alternative implementations of the SHA512 module must adjust their functions' prototype accordingly.

include/mbedtls/sha512.h

@@ -134,13 +134,14 @@ int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx,
  * \param ctx      The SHA-512 context. This must be initialized
  *                 and have a hash operation started.
  * \param output   The SHA-384 or SHA-512 checksum result.
- *                 This must be a writable buffer of length \c 64 Bytes.
+ *                 This must be a writable buffer of length \c 64 bytes
+ *                 for SHA-512, 48 bytes for SHA-384.
  *
  * \return         \c 0 on success.
  * \return         A negative error code on failure.
  */
 int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx,
-                               unsigned char output[64] );
+                               unsigned char *output );
 
 /**
  * \brief          This function processes a single data block within
@@ -171,7 +172,8 @@ int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
  *                 a readable buffer of length \p ilen Bytes.
  * \param ilen     The length of the input data in Bytes.
  * \param output   The SHA-384 or SHA-512 checksum result.
- *                 This must be a writable buffer of length \c 64 Bytes.
+ *                 This must be a writable buffer of length \c 64 bytes
+ *                 for SHA-512, 48 bytes for SHA-384.
  * \param is384    Determines which function to use. This must be either
  *                 \c 0 for SHA-512, or \c 1 for SHA-384.
  *
@@ -184,7 +186,7 @@ int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
  */
 int mbedtls_sha512_ret( const unsigned char *input,
                         size_t ilen,
-                        unsigned char output[64],
+                        unsigned char *output,
                         int is384 );
 
 #if defined(MBEDTLS_SELF_TEST)

library/sha512.c

@@ -380,7 +380,7 @@ int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx,
  * SHA-512 final digest
  */
 int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx,
-                               unsigned char output[64] )
+                               unsigned char *output )
 {
     int ret = MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED;
     unsigned used;
@@ -453,7 +453,7 @@ int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx,
  */
 int mbedtls_sha512_ret( const unsigned char *input,
                     size_t ilen,
-                    unsigned char output[64],
+                    unsigned char *output,
                     int is384 )
 {
     int ret = MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED;