crypto.ecdsa: improve safety checking, unify signing (and verifying) api to accept options (#23463)

Author: blackshirt

cmd/tools/modules/testing/common.v

@@ -252,6 +252,7 @@ pub fn new_test_session(_vargs string, will_compile bool) TestSession {
 			skip_files << 'vlib/v/tests/websocket_logger_interface_should_compile_test.v' // requires OpenSSL
 			skip_files << 'vlib/crypto/ecdsa/ecdsa_test.v' // requires OpenSSL
 			skip_files << 'vlib/crypto/ecdsa/util_test.v' // requires OpenSSL
+			skip_files << 'vlib/crypto/ecdsa/example/ecdsa_seed_test.v' // requires OpenSSL
 			$if tinyc {
 				skip_files << 'examples/database/orm.v' // try fix it
 			}
@@ -284,13 +285,15 @@ pub fn new_test_session(_vargs string, will_compile bool) TestSession {
 			skip_files << 'vlib/net/openssl/openssl_compiles_test.c.v'
 			skip_files << 'vlib/crypto/ecdsa/ecdsa_test.v' // requires OpenSSL
 			skip_files << 'vlib/crypto/ecdsa/util_test.v' // requires OpenSSL
+			skip_files << 'vlib/crypto/ecdsa/example/ecdsa_seed_test.v' // requires OpenSSL
 			skip_files << 'vlib/x/ttf/ttf_test.v'
 			skip_files << 'vlib/encoding/iconv/iconv_test.v' // needs libiconv to be installed
 		}
 		if github_job == 'tests-sanitize-memory-clang' {
 			skip_files << 'vlib/net/openssl/openssl_compiles_test.c.v'
 			skip_files << 'vlib/crypto/ecdsa/ecdsa_test.v' // requires OpenSSL
 			skip_files << 'vlib/crypto/ecdsa/util_test.v' // requires OpenSSL
+			skip_files << 'vlib/crypto/ecdsa/example/ecdsa_seed_test.v' // requires OpenSSL
 			// Fails compilation with: `/usr/bin/ld: /lib/x86_64-linux-gnu/libpthread.so.0: error adding symbols: DSO missing from command line`
 			skip_files << 'examples/sokol/sounds/simple_sin_tones.v'
 		}

vlib/crypto/ecdsa/README.md

@@ -2,7 +2,38 @@
 
 `ecdsa` module for V language. Its a wrapper on top of openssl ecdsa functionality.
 Its currently (expanded) to support the following curves:
+
 - NIST P-256 curve, commonly referred as prime256v1 or secp256r1
 - NIST P-384 curve, commonly referred as secp384r1 
 - NIST P-521 curve, commonly referred as secp521r1
-- A famous Bitcoin curve, commonly referred as secp256k1
+- 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
+
+fn main() {
+	// create default NIST P-256 secp256r1 curve key pair. If you wish to generate another curve,
+	// use: `pbkey, pvkey := ecdsa.generate_key(nid: .secp521r1)!` instead.
+	pbkey, pvkey := ecdsa.generate_key()!
+
+	message_tobe_signed := 'Hello ecdsa'.bytes()
+	// create a signature with the recommended hash
+	signature := pvkey.sign(message_tobe_signed)!
+
+	// verify the message with the signature
+	verified := pbkey.verify(message_tobe_signed, signature)!
+	dump(verified) // should be true
+
+	// free allocated keys when you have done with your work.
+	pbkey.free()
+	pvkey.free()
+}
+```