mbedtls_ecp_write_key: document and test larger output buffer
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h
index df59891..231832b 100644
--- a/include/mbedtls/ecp.h
+++ b/include/mbedtls/ecp.h
@@ -1286,11 +1286,28 @@
/**
* \brief This function exports an elliptic curve private key.
*
+ * \note Note that although this function accepts an output
+ * buffer that is larger than the key, most key import
+ * interfaces require the output to be trimmed to the
+ * key's nominal length. It is generally simplest to
+ * pass the key's nominal length as \c buflen, after
+ * checking that the output buffer is large enough.
+ * See the description of the \p buflen parameter for
+ * how to calculate the nominal length.
+ *
* \param key The private key.
* \param buf The output buffer for containing the binary representation
- * of the key. (Big endian integer for Weierstrass curves, byte
- * string for Montgomery curves.)
+ * of the key.
+ * For Weierstrass curves, this is the big-endian
+ * representation, padded with null bytes at the beginning
+ * to reach \p buflen bytes.
+ * For Montgomery curves, this is the standard byte string
+ * representation (which is little-endian), padded with
+ * null bytes at the end to reach \p buflen bytes.
* \param buflen The total length of the buffer in bytes.
+ * The length of the output is always
+ * (`grp->nbits` + 7) / 8 bytes
+ * where `grp->nbits` is the private key size in bits.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the \p key
diff --git a/tests/suites/test_suite_ecp.data b/tests/suites/test_suite_ecp.data
index 6211fb7..7d3dd1a 100644
--- a/tests/suites/test_suite_ecp.data
+++ b/tests/suites/test_suite_ecp.data
@@ -550,6 +550,54 @@
depends_on:MBEDTLS_ECP_DP_CURVE25519_ENABLED
mbedtls_ecp_read_key:MBEDTLS_ECP_DP_CURVE25519:"70076d0a7318a57d3c16c17251b26645df4c2f87ebc0992ab177fba51db92c6a":0:1
+ECP write key: secp256r1, nominal
+depends_on:MBEDTLS_ECP_DP_SECP256R1_ENABLED
+ecp_write_key:MBEDTLS_ECP_DP_SECP256R1:"f12a1320760270a83cbffd53f6031ef76a5d86c8a204f2c30ca9ebf51f0f0ea7":32:0
+
+ECP write key: secp256r1, output longer by 1
+depends_on:MBEDTLS_ECP_DP_SECP256R1_ENABLED
+ecp_write_key:MBEDTLS_ECP_DP_SECP256R1:"f12a1320760270a83cbffd53f6031ef76a5d86c8a204f2c30ca9ebf51f0f0ea7":33:0
+
+ECP write key: secp256r1, output longer by 32
+depends_on:MBEDTLS_ECP_DP_SECP256R1_ENABLED
+ecp_write_key:MBEDTLS_ECP_DP_SECP256R1:"f12a1320760270a83cbffd53f6031ef76a5d86c8a204f2c30ca9ebf51f0f0ea7":64:0
+
+ECP write key: secp256r1, output longer by 33
+depends_on:MBEDTLS_ECP_DP_SECP256R1_ENABLED
+ecp_write_key:MBEDTLS_ECP_DP_SECP256R1:"f12a1320760270a83cbffd53f6031ef76a5d86c8a204f2c30ca9ebf51f0f0ea7":65:0
+
+ECP write key: secp384r1, nominal
+depends_on:MBEDTLS_ECP_DP_SECP384R1_ENABLED
+ecp_write_key:MBEDTLS_ECP_DP_SECP384R1:"d27335ea71664af244dd14e9fd1260715dfd8a7965571c48d709ee7a7962a156d706a90cbcb5df2986f05feadb9376f1":48:0
+
+ECP write key: secp384r1, output longer by 1
+depends_on:MBEDTLS_ECP_DP_SECP384R1_ENABLED
+ecp_write_key:MBEDTLS_ECP_DP_SECP384R1:"d27335ea71664af244dd14e9fd1260715dfd8a7965571c48d709ee7a7962a156d706a90cbcb5df2986f05feadb9376f1":49:0
+
+ECP write key: secp384r1, output longer by 48
+depends_on:MBEDTLS_ECP_DP_SECP384R1_ENABLED
+ecp_write_key:MBEDTLS_ECP_DP_SECP384R1:"d27335ea71664af244dd14e9fd1260715dfd8a7965571c48d709ee7a7962a156d706a90cbcb5df2986f05feadb9376f1":96:0
+
+ECP write key: secp384r1, output longer by 49
+depends_on:MBEDTLS_ECP_DP_SECP384R1_ENABLED
+ecp_write_key:MBEDTLS_ECP_DP_SECP384R1:"d27335ea71664af244dd14e9fd1260715dfd8a7965571c48d709ee7a7962a156d706a90cbcb5df2986f05feadb9376f1":97:0
+
+ECP write key: Curve25519, nominal
+depends_on:MBEDTLS_ECP_DP_CURVE25519_ENABLED
+ecp_write_key:MBEDTLS_ECP_DP_CURVE25519:"a046e36bf0527c9d3b16154b82465edd62144c0ac1fc5a18506a2244ba449a44":32:0
+
+ECP write key: Curve25519, output longer by 1
+depends_on:MBEDTLS_ECP_DP_CURVE25519_ENABLED
+ecp_write_key:MBEDTLS_ECP_DP_CURVE25519:"a046e36bf0527c9d3b16154b82465edd62144c0ac1fc5a18506a2244ba449a44":33:0
+
+ECP write key: Curve25519, output longer by 32
+depends_on:MBEDTLS_ECP_DP_CURVE25519_ENABLED
+ecp_write_key:MBEDTLS_ECP_DP_CURVE25519:"a046e36bf0527c9d3b16154b82465edd62144c0ac1fc5a18506a2244ba449a44":64:0
+
+ECP write key: Curve25519, output longer by 33
+depends_on:MBEDTLS_ECP_DP_CURVE25519_ENABLED
+ecp_write_key:MBEDTLS_ECP_DP_CURVE25519:"a046e36bf0527c9d3b16154b82465edd62144c0ac1fc5a18506a2244ba449a44":65:0
+
ECP mod p192 small (more than 192 bits, less limbs than 2 * 192 bits)
depends_on:MBEDTLS_ECP_DP_SECP192R1_ENABLED
ecp_fast_mod:MBEDTLS_ECP_DP_SECP192R1:"0100000000000103010000000000010201000000000001010100000000000100"
diff --git a/tests/suites/test_suite_ecp.function b/tests/suites/test_suite_ecp.function
index 443bc08..aff5ba4 100644
--- a/tests/suites/test_suite_ecp.function
+++ b/tests/suites/test_suite_ecp.function
@@ -1383,6 +1383,53 @@
}
/* END_CASE */
+/* BEGIN_CASE */
+void ecp_write_key(int grp_id, data_t *in_key,
+ int exported_size, int expected_ret)
+{
+ mbedtls_ecp_keypair key;
+ mbedtls_ecp_keypair_init(&key);
+ unsigned char *exported = NULL;
+
+ TEST_EQUAL(mbedtls_ecp_read_key(grp_id, &key, in_key->x, in_key->len), 0);
+
+ TEST_CALLOC(exported, exported_size);
+ TEST_EQUAL(mbedtls_ecp_write_key(&key, exported, exported_size),
+ expected_ret);
+
+ if (expected_ret == 0) {
+ size_t length = (key.grp.nbits + 7) / 8;
+ TEST_LE_U(length, exported_size);
+
+ const unsigned char *key_start = NULL;
+ const unsigned char *zeros_start = NULL;
+ switch (mbedtls_ecp_get_type(&key.grp)) {
+ case MBEDTLS_ECP_TYPE_SHORT_WEIERSTRASS:
+ key_start = exported + exported_size - length;
+ zeros_start = exported;
+ break;
+ case MBEDTLS_ECP_TYPE_MONTGOMERY:
+ key_start = exported;
+ zeros_start = exported + length;
+ break;
+ default:
+ TEST_FAIL("Unknown ECP curve type");
+ break;
+ }
+ TEST_MEMORY_COMPARE(in_key->x, in_key->len,
+ key_start, length);
+ for (size_t i = 0; i < exported_size - length; i++) {
+ mbedtls_test_set_step(i);
+ TEST_EQUAL(zeros_start[i], 0);
+ }
+ }
+
+exit:
+ mbedtls_ecp_keypair_free(&key);
+ mbedtls_free(exported);
+}
+/* END_CASE */
+
/* BEGIN_CASE depends_on:HAVE_FIX_NEGATIVE */
void fix_negative(data_t *N_bin, int c, int bits)
{