[crypto] Rename otcrypto_ed25519_keygen function

nasahlpa · nasahlpa · commit 8b813365a59f · 2026-04-24T16:29:57.000+02:00
As this function creates a public key from a given private one,
reflect this in the function comment header as well as the name.

Signed-off-by: Pascal Nasahl &lt;nasahlpa@lowrisc.org&gt;
diff --git a/doc/security/cryptolib/cryptolib_api.md b/doc/security/cryptolib/cryptolib_api.md
@@ -469,7 +469,7 @@ Each party should generate a key pair, exchange public keys, and then generate t
 
 For Ed25519 (a curve-specialized version of EdDSA, the Edwards curve digital signature algorithm), the cryptography library supports keypair generation, signature generation, and signature verification.
 
-{{#header-snippet sw/device/lib/crypto/include/ecc_curve25519.h otcrypto_ed25519_keygen }}
+{{#header-snippet sw/device/lib/crypto/include/ecc_curve25519.h otcrypto_ed25519_public_key_from_private }}
 {{#header-snippet sw/device/lib/crypto/include/ecc_curve25519.h otcrypto_ed25519_sign }}
 {{#header-snippet sw/device/lib/crypto/include/ecc_curve25519.h otcrypto_ed25519_verify }}
 {{#header-snippet sw/device/lib/crypto/include/ecc_curve25519.h otcrypto_ed25519_sign_verify }}
@@ -520,8 +520,8 @@ Each party should generate a key pair, exchange public keys, and then generate t
 
 #### Ed25519
 
-{{#header-snippet sw/device/lib/crypto/include/ecc_curve25519.h otcrypto_ed25519_keygen_async_start }}
-{{#header-snippet sw/device/lib/crypto/include/ecc_curve25519.h otcrypto_ed25519_keygen_async_finalize }}
+{{#header-snippet sw/device/lib/crypto/include/ecc_curve25519.h otcrypto_ed25519_public_key_from_private_async_start }}
+{{#header-snippet sw/device/lib/crypto/include/ecc_curve25519.h otcrypto_ed25519_public_key_from_private_async_finalize }}
 
 {{#header-snippet sw/device/lib/crypto/include/ecc_curve25519.h otcrypto_ed25519_sign_part1_async_start }}
 {{#header-snippet sw/device/lib/crypto/include/ecc_curve25519.h otcrypto_ed25519_sign_part2_async_start }}
diff --git a/sw/device/lib/crypto/impl/ecc_curve25519.c b/sw/device/lib/crypto/impl/ecc_curve25519.c
@@ -231,16 +231,17 @@ static status_t ed25519_mask_scalar(uint32_t *scalar, size_t scalar_len,
   return OTCRYPTO_OK;
 }
 
-otcrypto_status_t otcrypto_ed25519_keygen(
+otcrypto_status_t otcrypto_ed25519_public_key_from_private(
     const otcrypto_unblinded_key_t *private_key,
     otcrypto_unblinded_key_t *public_key) {
   if (public_key == NULL || public_key->key == NULL) {
     return OTCRYPTO_BAD_ARGS;
   }
   // Start the execution of the key generation.
-  HARDENED_TRY(otcrypto_ed25519_keygen_async_start(private_key));
+  HARDENED_TRY(
+      otcrypto_ed25519_public_key_from_private_async_start(private_key));
   // Finish the keygen operation and get the public key.
-  return otcrypto_ed25519_keygen_async_finalize(public_key);
+  return otcrypto_ed25519_public_key_from_private_async_finalize(public_key);
 }
 
 otcrypto_status_t otcrypto_ed25519_sign(
@@ -334,7 +335,7 @@ otcrypto_status_t otcrypto_ed25519_sign_verify(
   return OTCRYPTO_OK;
 }
 
-otcrypto_status_t otcrypto_ed25519_keygen_async_start(
+otcrypto_status_t otcrypto_ed25519_public_key_from_private_async_start(
     const otcrypto_unblinded_key_t *private_key) {
   // Check the private key.
   HARDENED_TRY(ed25519_key_check(private_key));
@@ -367,7 +368,7 @@ otcrypto_status_t otcrypto_ed25519_keygen_async_start(
   return otcrypto_eval_exit(OTCRYPTO_OK);
 }
 
-otcrypto_status_t otcrypto_ed25519_keygen_async_finalize(
+otcrypto_status_t otcrypto_ed25519_public_key_from_private_async_finalize(
     otcrypto_unblinded_key_t *public_key) {
   // Finalize the keygen operation and retrieve the public key.
   HARDENED_TRY_WIPE_DMEM(curve25519_keygen_finalize(public_key->key));
diff --git a/sw/device/lib/crypto/include/ecc_curve25519.h b/sw/device/lib/crypto/include/ecc_curve25519.h
@@ -29,21 +29,23 @@ typedef enum otcrypto_eddsa_sign_mode {
 } otcrypto_eddsa_sign_mode_t;
 
 /**
- * Generates a key pair for Ed25519.
+ * Derives the Ed25519 public key corresponding to a given private key.
  *
- * The caller should allocate and partially populate the public key struct,
- * including populating the key configuration and allocating space for the
- * keyblob. For a hardware-backed key, use the private key handle returned by
- * `otcrypto_hw_backed_key`. Otherwise, the mode should indicate Ed25519 and the
- * keyblob should be 80 bytes. The value in the `checksum` field of the
- * key struct will be populated by the key generation function.
+ * The private key must be a pre-existing 32-byte Ed25519 seed with a valid
+ * checksum (e.g. as returned by an import function). The public key is
+ * derived by SHA-512-hashing the seed, clamping the result to obtain the
+ * secret scalar, and multiplying the Ed25519 base point by that scalar.
  *
- * @param[out] private_key Pointer to the unblinded private key struct.
- * @param[out] public_key Pointer to the unblinded public key struct.
- * @return Result of the Ed25519 key generation.
+ * The caller must allocate the public key struct and its `key` buffer
+ * (32 bytes) before calling this function. The `checksum` field will be
+ * populated on success.
+ *
+ * @param[in]  private_key Pointer to the private key seed struct.
+ * @param[out] public_key  Pointer to the public key struct to populate.
+ * @return Result of the Ed25519 public key derivation.
  */
 OT_WARN_UNUSED_RESULT
-otcrypto_status_t otcrypto_ed25519_keygen(
+otcrypto_status_t otcrypto_ed25519_public_key_from_private(
     const otcrypto_unblinded_key_t *private_key,
     otcrypto_unblinded_key_t *public_key);
 
@@ -106,27 +108,29 @@ otcrypto_status_t otcrypto_ed25519_sign_verify(
 /**
  * Starts asynchronous key generation for Ed25519.
  *
- * See `otcrypto_ed25519_keygen` for requirements on input values.
+ * See `otcrypto_ed25519_public_key_from_private` for requirements on input
+ * values.
  *
  * @param private_key Source structure for private key, or key handle.
  * @return Result of asynchronous Ed25519 keygen start operation.
  */
 OT_WARN_UNUSED_RESULT
-otcrypto_status_t otcrypto_ed25519_keygen_async_start(
+otcrypto_status_t otcrypto_ed25519_public_key_from_private_async_start(
     const otcrypto_unblinded_key_t *private_key);
 
 /**
  * Finalizes asynchronous key generation for Ed25519.
  *
- * See `otcrypto_ed25519_keygen` for requirements on input values.
+ * See `otcrypto_ed25519_public_key_from_private` for requirements on input
+ * values.
  *
  * May block until the operation is complete.
  *
  * @param[out] public_key Pointer to the unblinded public key struct.
  * @return Result of asynchronous ed25519 keygen finalize operation.
  */
 OT_WARN_UNUSED_RESULT
-otcrypto_status_t otcrypto_ed25519_keygen_async_finalize(
+otcrypto_status_t otcrypto_ed25519_public_key_from_private_async_finalize(
     otcrypto_unblinded_key_t *public_key);
 
 /**
diff --git a/sw/device/tests/crypto/ed25519_functest.c b/sw/device/tests/crypto/ed25519_functest.c
@@ -110,7 +110,8 @@ status_t ed25519_kat_test(void) {
   };
 
   // Run ed25519 key generation.
-  CHECK_STATUS_OK(otcrypto_ed25519_keygen(&private_key, &public_key));
+  CHECK_STATUS_OK(
+      otcrypto_ed25519_public_key_from_private(&private_key, &public_key));
   // Check the ed25519 key generation result.
   TRY_CHECK_ARRAYS_EQ(kPublicKey, public_key.key, kEd25519PublicKeyWords);
 
@@ -168,7 +169,8 @@ static status_t hasheddsa_test(void) {
       .key = public_key_buf,
   };
 
-  CHECK_STATUS_OK(otcrypto_ed25519_keygen(&private_key, &public_key));
+  CHECK_STATUS_OK(
+      otcrypto_ed25519_public_key_from_private(&private_key, &public_key));
 
   otcrypto_const_byte_buf_t input_message =
       OTCRYPTO_MAKE_BUF(otcrypto_const_byte_buf_t, (const uint8_t *)kMessage,
@@ -279,26 +281,26 @@ static status_t run_negative_tests(void) {
   otcrypto_unblinded_key_t bad_key = valid_priv;
   bad_key.key_length = 31;
   bad_key.checksum = integrity_unblinded_checksum(&bad_key);
-  CHECK(otcrypto_ed25519_keygen(&bad_key, &valid_pub).value ==
+  CHECK(otcrypto_ed25519_public_key_from_private(&bad_key, &valid_pub).value ==
         OTCRYPTO_BAD_ARGS.value);
 
   bad_key = valid_priv;
   bad_key.key_mode = kOtcryptoKeyModeEcdsaP256;
   bad_key.checksum = integrity_unblinded_checksum(&bad_key);
-  CHECK(otcrypto_ed25519_keygen(&bad_key, &valid_pub).value ==
+  CHECK(otcrypto_ed25519_public_key_from_private(&bad_key, &valid_pub).value ==
         OTCRYPTO_BAD_ARGS.value);
 
   bad_key = valid_priv;
   bad_key.key = NULL;
-  CHECK(otcrypto_ed25519_keygen(&bad_key, &valid_pub).value ==
+  CHECK(otcrypto_ed25519_public_key_from_private(&bad_key, &valid_pub).value ==
         OTCRYPTO_BAD_ARGS.value);
 
   bad_key = valid_priv;
   bad_key.checksum ^= 0xFFFFFFFF;
-  CHECK(otcrypto_ed25519_keygen(&bad_key, &valid_pub).value ==
+  CHECK(otcrypto_ed25519_public_key_from_private(&bad_key, &valid_pub).value ==
         OTCRYPTO_BAD_ARGS.value);
 
-  CHECK(otcrypto_ed25519_keygen(NULL, &valid_pub).value ==
+  CHECK(otcrypto_ed25519_public_key_from_private(NULL, &valid_pub).value ==
         OTCRYPTO_BAD_ARGS.value);
 
   // Test NULL data with len > 0 or invalid mode
diff --git a/sw/device/tests/crypto/otcrypto_interface.c b/sw/device/tests/crypto/otcrypto_interface.c
@@ -119,14 +119,17 @@ volatile otcrypto_interface_t otcrypto = {
     .cshake256 = &otcrypto_cshake256,
 
     // Ed25519 (blocking).
-    .ed25519_keygen = &otcrypto_ed25519_keygen,
+    .ed25519_public_key_from_private =
+        &otcrypto_ed25519_public_key_from_private,
     .ed25519_sign = &otcrypto_ed25519_sign,
     .ed25519_sign_verify = &otcrypto_ed25519_sign_verify,
     .ed25519_verify = &otcrypto_ed25519_verify,
 
     // Ed25519 (async).
-    .ed25519_keygen_async_start = &otcrypto_ed25519_keygen_async_start,
-    .ed25519_keygen_async_finalize = &otcrypto_ed25519_keygen_async_finalize,
+    .ed25519_public_key_from_private_async_start =
+        &otcrypto_ed25519_public_key_from_private_async_start,
+    .ed25519_public_key_from_private_async_finalize =
+        &otcrypto_ed25519_public_key_from_private_async_finalize,
     .ed25519_sign_part1_async_start = &otcrypto_ed25519_sign_part1_async_start,
     .ed25519_sign_part2_async_start = &otcrypto_ed25519_sign_part2_async_start,
     .ed25519_sign_async_finalize = &otcrypto_ed25519_sign_async_finalize,
diff --git a/sw/device/tests/crypto/otcrypto_interface.h b/sw/device/tests/crypto/otcrypto_interface.h
@@ -198,8 +198,8 @@ typedef struct otcrypto_interface_t {
                                  otcrypto_hash_digest_t *);
 
   // ED25519
-  otcrypto_status_t (*ed25519_keygen)(const otcrypto_unblinded_key_t *,
-                                      otcrypto_unblinded_key_t *);
+  otcrypto_status_t (*ed25519_public_key_from_private)(
+      const otcrypto_unblinded_key_t *, otcrypto_unblinded_key_t *);
   otcrypto_status_t (*ed25519_sign)(const otcrypto_unblinded_key_t *,
                                     const otcrypto_const_byte_buf_t *,
                                     otcrypto_eddsa_sign_mode_t,
@@ -214,9 +214,9 @@ typedef struct otcrypto_interface_t {
                                       otcrypto_eddsa_sign_mode_t,
                                       const otcrypto_const_word32_buf_t *,
                                       hardened_bool_t *);
-  otcrypto_status_t (*ed25519_keygen_async_start)(
+  otcrypto_status_t (*ed25519_public_key_from_private_async_start)(
       const otcrypto_unblinded_key_t *);
-  otcrypto_status_t (*ed25519_keygen_async_finalize)(
+  otcrypto_status_t (*ed25519_public_key_from_private_async_finalize)(
       otcrypto_unblinded_key_t *);
   otcrypto_status_t (*ed25519_sign_async_start)(
       const otcrypto_blinded_key_t *, const otcrypto_const_byte_buf_t *,
