7.5 KiB
module ecdsa
Contents
- generate_key
- new_key_from_seed
- privkey_from_string
- pubkey_from_bytes
- pubkey_from_string
- PrivateKey.new
- HashConfig
- Nid
- C.BIO
- CurveOptions
- PrivateKey
- PublicKey
- SignerOpts
generate_key
fn generate_key(opt CurveOptions) !(PublicKey, PrivateKey)
generate_key generates a new key pair. If opt was not provided, its default to prime256v1 curve. If you want another curve, use pubkey, pivkey := ecdsa.generate_key(nid: .secp384r1)! instead.
new_key_from_seed
fn new_key_from_seed(seed []u8, opt CurveOptions) !PrivateKey
new_key_from_seed creates a new private key from the seed bytes. If opt was not provided, its default to prime256v1 curve.
Notes on the seed:
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 66 bytes length for p-521. Its recommended to use seed with bytes length matching with underlying curve key size.
privkey_from_string
fn privkey_from_string(s string) !PrivateKey
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 ecdsa_seed_test.v file for example of usage.
pubkey_from_bytes
fn pubkey_from_bytes(bytes []u8) !PublicKey
pubkey_from_bytes loads ECDSA Public Key from bytes array. The bytes of data should be a valid of ASN.1 DER serialized SubjectPublicKeyInfo structrue of RFC 5480. Otherwise, its should an error. Typically, you can load the bytes from pem formatted of ecdsa public key.
Examples:
import crypto.pem
import crypto.ecdsa
const pubkey_sample = '-----BEGIN PUBLIC KEY-----
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAE+P3rhFkT1fXHYbY3CpcBdh6xTC74MQFx
cftNVD3zEPVzo//OalIVatY162ksg8uRWBdvFFuHZ9OMVXkbjwWwhcXP7qmI9rOS
LR3AGUldy+bBpV2nT306qCIwgUAMeOJP
-----END PUBLIC KEY-----'
block, _ := pem.decode(pubkey_sample) or { panic(err) }
pubkey := ecdsa.pubkey_from_bytes(block.data)!
pubkey_from_string
fn pubkey_from_string(s string) !PublicKey
pubkey_from_string loads a PublicKey from valid PEM-formatted string in s.
PrivateKey.new
fn PrivateKey.new(opt CurveOptions) !PrivateKey
PrivateKey.new creates a new key pair. By default, it would create a prime256v1 based key. Dont forget to call .free() after finish with your key.
HashConfig
enum HashConfig {
with_recommended_hash
with_no_hash
with_custom_hash
}
HashConfig is an enumeration of the possible options for key signing (verifying).
Nid
enum Nid {
prime256v1 = C.NID_X9_62_prime256v1
secp384r1 = C.NID_secp384r1
secp521r1 = C.NID_secp521r1
secp256k1 = C.NID_secp256k1
}
Nid is an enumeration of the supported curves
C.BIO
struct C.BIO {}
CurveOptions
struct CurveOptions {
pub mut:
// default to NIST P-256 curve
nid Nid = .prime256v1
// by default, allow arbitrary size of seed bytes as key.
// Set it to `true` when you need fixed size, using the curve key size.
// Its main purposes is to support the `.new_key_from_seed` call.
fixed_size bool
}
CurveOptions represents configuration options to drive keypair generation.
PrivateKey
struct PrivateKey {
// The new high level of keypair opaque
evpkey &C.EVP_PKEY
mut:
// ks_flag with .flexible value allowing
// flexible-size seed bytes as key.
// When it is `.fixed`, it will use the underlying key size.
ks_flag KeyFlag = .flexible
// ks_size stores size of the seed bytes when ks_flag was .flexible.
// You should set it to a non zero value
ks_size int
}
PrivateKey represents ECDSA private key. Actually its a key pair, contains private key and public key parts.
sign
fn (pv PrivateKey) sign(message []u8, opt SignerOpts) ![]u8
sign performs signing the message with the options. By default options, it will perform hashing before signing the message.
sign_with_options
fn (pv PrivateKey) sign_with_options(message []u8, opt SignerOpts) ![]u8
sign_with_options signs message with the options. It will be deprecated, Use PrivateKey.sign() instead.
bytes
fn (pv PrivateKey) bytes() ![]u8
bytes represent private key as bytes.
seed
fn (pv PrivateKey) seed() ![]u8
seed gets the seed (private key bytes). It will be deprecated. Use PrivateKey.bytes() instead.
public_key
fn (pv PrivateKey) public_key() !PublicKey
public_key gets the PublicKey from private key.
equal
fn (priv_key PrivateKey) equal(other PrivateKey) bool
equal compares two private keys was equal.
free
fn (pv &PrivateKey) free()
free clears out allocated memory for PrivateKey. Dont use PrivateKey after calling .free()
PublicKey
struct PublicKey {
// The new high level of keypair opaque
evpkey &C.EVP_PKEY
}
PublicKey represents ECDSA public key for verifying message.
bytes
fn (pbk PublicKey) bytes() ![]u8
bytes gets the bytes of public key.
equal
fn (pub_key PublicKey) equal(other PublicKey) bool
equal compares two public keys was equal.
free
fn (pb &PublicKey) free()
free clears out allocated memory for PublicKey. Dont use PublicKey after calling .free()
verify
fn (pb PublicKey) verify(message []u8, sig []u8, opt SignerOpts) !bool
verify verifies a message with the signature are valid with public key provided . You should provide it with the same SignerOpts used with the .sign() call. or verify would fail (false).
SignerOpts
struct SignerOpts {
pub mut:
// default to .with_recommended_hash
hash_config HashConfig = .with_recommended_hash
// make sense when HashConfig != with_recommended_hash
allow_smaller_size bool
allow_custom_hash bool
// set to non-nil if allow_custom_hash was true
custom_hash &hash.Hash = unsafe { nil }
}
SignerOpts represents configuration options to drive signing and verifying process.