From 6623ac21c7f9237b0bb4bb4830fda0438ec3320b Mon Sep 17 00:00:00 2001
From: blackshirt <blackshirt@users.noreply.github.com>
Date: Mon, 10 Mar 2025 15:37:00 +0700
Subject: [PATCH] crypto.ecdsa: update and cleanup the documentation (#23897)

---
 vlib/crypto/ecdsa/README.md |  7 -------
 vlib/crypto/ecdsa/ecdsa.v   | 21 +++++++--------------
 vlib/crypto/ecdsa/util.v    |  6 +++---
 3 files changed, 10 insertions(+), 24 deletions(-)

diff --git a/vlib/crypto/ecdsa/README.md b/vlib/crypto/ecdsa/README.md
index 14cf0d7851..68cb127813 100644
--- a/vlib/crypto/ecdsa/README.md
+++ b/vlib/crypto/ecdsa/README.md
@@ -8,13 +8,6 @@ Its currently (expanded) to support the following curves:
 - NIST P-521 curve, commonly referred as secp521r1
 - A famous Bitcoin curve, commonly referred as secp256k1
 
-> [!CAUTION]
-> This module using low level OpenSSL opaque methods that mostly has been deprecated 
-> in OpenSSL 3.0. 
-> Please be aware, likely it would not compile with `-cstrict` options until
-> its migrated into supported higher level API.
-
-
 # Example
 ```v
 import crypto.ecdsa
diff --git a/vlib/crypto/ecdsa/ecdsa.v b/vlib/crypto/ecdsa/ecdsa.v
index 1378f8db8b..1d15c2134a 100644
--- a/vlib/crypto/ecdsa/ecdsa.v
+++ b/vlib/crypto/ecdsa/ecdsa.v
@@ -54,6 +54,7 @@ fn (nid Nid) str() string {
 	}
 }
 
+// CurveOptions represents configuration options to drive keypair generation.
 @[params]
 pub struct CurveOptions {
 pub mut:
@@ -94,7 +95,7 @@ enum KeyFlag {
 }
 
 // generate_key generates a new key pair. If opt was not provided, its default to prime256v1 curve.
-// If you want another curve, use in the following manner: `pubkey, pivkey := ecdsa.generate_key(nid: .secp384r1)!`
+// If you want another curve, use `pubkey, pivkey := ecdsa.generate_key(nid: .secp384r1)!` instead.
 pub fn generate_key(opt CurveOptions) !(PublicKey, PrivateKey) {
 	// This can be simplified to just more simpler one
 	pv := PrivateKey.new(opt)!
@@ -111,7 +112,7 @@ pub fn generate_key(opt CurveOptions) !(PublicKey, PrivateKey) {
 // You should make sure, the seed bytes come from a cryptographically secure random generator,
 // likes the `crypto.rand` or other trusted sources.
 // Internally, the seed size's would be checked to not exceed the key size of underlying curve,
-// ie, 32 bytes length for p-256 and secp256k1, 48 bytes length for p-384 and 64 bytes length for p-521.
+// ie, 32 bytes length for p-256 and secp256k1, 48 bytes length for p-384 and 66 bytes length for p-521.
 // Its recommended to use seed with bytes length matching with underlying curve key size.
 pub fn new_key_from_seed(seed []u8, opt CurveOptions) !PrivateKey {
 	// Early exit check
@@ -276,9 +277,6 @@ pub fn (pv PrivateKey) seed() ![]u8 {
 
 // public_key gets the PublicKey from private key.
 pub fn (pv PrivateKey) public_key() !PublicKey {
-	// Check if EVP_PKEY opaque was availables or not.
-	// TODO: removes this check when its ready
-
 	bo := C.BIO_new(C.BIO_s_mem())
 	n := C.i2d_PUBKEY_bio(bo, pv.evpkey)
 	assert n != 0
@@ -292,17 +290,13 @@ pub fn (pv PrivateKey) public_key() !PublicKey {
 	}
 }
 
-// equal compares two private keys was equal. Its checks for two things, ie:
-//
-// - whether both of private keys lives under the same group (curve),
-// - compares if two private key bytes was equal.
+// equal compares two private keys was equal.
 pub fn (priv_key PrivateKey) equal(other PrivateKey) bool {
 	eq := C.EVP_PKEY_eq(voidptr(priv_key.evpkey), voidptr(other.evpkey))
 	return eq == 1
 }
 
-// free clears out allocated memory for PrivateKey
-// Dont use PrivateKey after calling `.free()`
+// free clears out allocated memory for PrivateKey. Dont use PrivateKey after calling `.free()`
 pub fn (pv &PrivateKey) free() {
 	C.EVP_PKEY_free(pv.evpkey)
 }
@@ -321,14 +315,13 @@ pub fn (pb PublicKey) verify(message []u8, sig []u8, opt SignerOpts) !bool {
 	return verify_signature(pb.evpkey, sig, digest)
 }
 
-// Compare two public keys
+// equal compares two public keys was equal.
 pub fn (pub_key PublicKey) equal(other PublicKey) bool {
 	eq := C.EVP_PKEY_eq(voidptr(pub_key.evpkey), voidptr(other.evpkey))
 	return eq == 1
 }
 
-// free clears out allocated memory for PublicKey.
-// Dont use PublicKey after calling `.free()`
+// free clears out allocated memory for PublicKey. Dont use PublicKey after calling `.free()`
 pub fn (pb &PublicKey) free() {
 	C.EVP_PKEY_free(pb.evpkey)
 }
diff --git a/vlib/crypto/ecdsa/util.v b/vlib/crypto/ecdsa/util.v
index 39a84001f2..89e5f8bfbd 100644
--- a/vlib/crypto/ecdsa/util.v
+++ b/vlib/crypto/ecdsa/util.v
@@ -151,9 +151,9 @@ pub fn pubkey_from_string(s string) !PublicKey {
 }
 
 // privkey_from_string loads a PrivateKey from valid PEM-formatted string in s.
-// Underlying wrapper support for old secg and pkcs8 private key format, but this was not heavily tested.
-// This routine does not support for the pkcs8 EncryptedPrivateKeyInfo format.
-// See [usage_test.v](https://github.com/vlang/v/blob/master/vlib/crypto/ecdsa/example/ecdsa_seed_test.v) file
+// Underlying wrapper support for old SECG and PKCS8 private key format, but this was not heavily tested.
+// This routine does not support for the PKCS8 EncryptedPrivateKeyInfo format.
+// See [ecdsa_seed_test.v](https://github.com/vlang/v/blob/master/vlib/crypto/ecdsa/example/ecdsa_seed_test.v) file
 // for example of usage.
 pub fn privkey_from_string(s string) !PrivateKey {
 	if s.len == 0 {