From 7511d4aed79b58b8d211c2bd31b8014a7380d1bf Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Mon, 19 Feb 2024 13:56:39 +0100
Subject: [PATCH] ECP write/export key: document that these functions don't
 detect unset data

Fixes #8803.

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
---
 include/mbedtls/ecp.h | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h
index e3bde0180..0201963ab 100644
--- a/include/mbedtls/ecp.h
+++ b/include/mbedtls/ecp.h
@@ -1339,6 +1339,10 @@ int mbedtls_ecp_read_key(mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
  *                  See the description of the \p buflen parameter for
  *                  how to calculate the nominal length.
  *
+ * \note            If the private key was not set in \p key,
+ *                  the output is unspecified. Future versions
+ *                  may return an error in that case.
+ *
  * \param key       The private key.
  * \param buf       The output buffer for containing the binary representation
  *                  of the key.
@@ -1369,6 +1373,10 @@ int mbedtls_ecp_write_key(mbedtls_ecp_keypair *key,
 /**
  * \brief           This function exports an elliptic curve public key.
  *
+ * \note            If the public key was not set in \p key,
+ *                  the output is unspecified. Future versions
+ *                  may return an error in that case.
+ *
  * \param key       The public key.
  * \param format    The point format. This must be either
  *                  #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
@@ -1451,6 +1459,10 @@ mbedtls_ecp_group_id mbedtls_ecp_keypair_get_group_id(
  *                  Each of the output parameters can be a null pointer
  *                  if you do not need that parameter.
  *
+ * \note            If the private key or the public key was not set in \p key,
+ *                  the corresponding output is unspecified. Future versions
+ *                  may return an error in that case.
+ *
  * \param key       The key pair to export from.
  * \param grp       Slot for exported ECP group.
  *                  It must either be null or point to an initialized ECP group.