crypto

README

NeoFS Crypto library

This package contains useful methods to work with crypto-primitives, that used in NeoFS / NeoBlockchain.

Examples

Simple Marshal / Unmarshal ECDSA public key (PK):

// returns slice of 33 bytes marshaled public key
data := crypto.MarshalPublicKey(&sk.PublicKey)

// returns public key decoded from 33 bytes    
pk := crypto.UnmarshalPublicKey(data)

Simple Marshal / Unmarshal ECDSA private key (SK):

// returns slice of 32 bytes marshaled private key
data := crypto.MarshalPrivateKey(&sk)

// returns private key decoded from 32 bytes or error,
// if something whet wrong    
newSk, err := crypto.UnmarshalPrivateKey(data)

ECDSA Sign / Verify bytes using PK / SK

// Sign returns signature (slice of 65 bytes) of SK for passed message (slice of bytes),
// or error, if something went wrong:
signature, err := crypto.Sign(sk, message)

// Verify returns error message if PK is empty or
// passed wrong signature (slice of 65 bytes) for message (slice of bytes),
err := crypto.Verify(&sk.PublicKey, signature, message)  

RFC6979 Sign / Verify bytes using PK / SK

// Sign returns signature (slice of 64 bytes) of SK for passed message (slice of bytes),
// or error, if something went wrong:
signature, err := crypto.SignRFC6979(sk, message)

// Verify returns error message if PK is empty or
// passed wrong signature (slice of 64 bytes) for message (slice of bytes),
err := crypto.VerifyRFC6979(&sk.PublicKey, signature, message)  

WIF Encode / Decode private key (SK)

// WIFEncode encodes the given private key into a WIF string.
// if sk or sk.D is empty, returns error
wif, err := crypto.WIFEncode(sk)

// WIFDecode decoded the given WIF string into a private key.
// if something went wrong, returns error:
skFromWIF, err := crypto.WIFDecode(wif)

LoadPrivateKey

// Load private key from wif format
sk, err := crypto.LoadPrivateKey(wif_string)

// Load private key from hex string
sk, err := crypto.LoadPrivateKey(hex_string)

// Load private key from file
sk, err := crypto.LoadPrivateKey(file_path)

Documentation

Index

• Constants
• func LoadPrivateKey(val string) (*ecdsa.PrivateKey, error)
• func MarshalPrivateKey(key *ecdsa.PrivateKey) []byte
• func MarshalPublicKey(key *ecdsa.PublicKey) []byte
• func Sign(key *ecdsa.PrivateKey, msg []byte) ([]byte, error)
• func SignHash(key *ecdsa.PrivateKey, msgHash []byte) ([]byte, error)
• func SignRFC6979(key *ecdsa.PrivateKey, msg []byte) ([]byte, error)
• func SignRFC6979Hash(key *ecdsa.PrivateKey, msgHash []byte) ([]byte, error)
• func UnmarshalPrivateKey(data []byte) (*ecdsa.PrivateKey, error)
• func UnmarshalPublicKey(data []byte) *ecdsa.PublicKey
• func Verify(pub *ecdsa.PublicKey, msg, sig []byte) error
• func VerifyHash(pub *ecdsa.PublicKey, msgHash, sig []byte) error
• func VerifyRFC6979(key *ecdsa.PublicKey, msg, sig []byte) error
• func VerifyRFC6979Hash(key *ecdsa.PublicKey, msgHash, sig []byte) error
• func WIFDecode(wif string) (*ecdsa.PrivateKey, error)
• func WIFEncode(key *ecdsa.PrivateKey) (string, error)

Constants

const (
	// ErrEmptyPublicKey when PK passed to Verify method is nil.
	ErrEmptyPublicKey = internal.Error("empty public key")

	// ErrInvalidSignature when signature passed to Verify method is mismatch.
	ErrInvalidSignature = internal.Error("invalid signature")

	// ErrCannotUnmarshal when signature ([]byte) passed to Verify method has wrong format
	// and cannot be parsed.
	ErrCannotUnmarshal = internal.Error("could not unmarshal signature")

	// PrivateKeyCompressedSize is constant with compressed size of private key (SK).
	// D coordinate stored, recover PK by formula x, y = curve.ScalarBaseMul(d,bytes).
	PrivateKeyCompressedSize = 32

	// PublicKeyCompressedSize is constant with compressed size of public key (PK).
	PublicKeyCompressedSize = 33

	// PublicKeyUncompressedSize is constant with uncompressed size of public key (PK).
	// First byte always should be 0x4 other 64 bytes is X and Y (32 bytes per coordinate).
	// 2 * 32 + 1
	PublicKeyUncompressedSize = 65
)

const (
	// RFC6979SignatureSize contains r and s coordinates (32 bytes)
	RFC6979SignatureSize = 64

	// ErrWrongHashSize when passed signature to VerifyRFC6979 has wrong size.
	ErrWrongHashSize = internal.Error("wrong hash size")

	// ErrWrongSignature when passed signature to VerifyRFC6979 isn't valid.
	ErrWrongSignature = internal.Error("wrong signature")
)

const (
	// WIFLength constant length of WIF string.
	WIFLength = 38

	// ErrBadWIF when passed WIF-string could not be decoded from base58.
	ErrBadWIF = internal.Error("bad wif")

	// ErrBadChecksum when passed WIF-string could not be verified
	// by last 4 bytes signature.
	ErrBadChecksum = internal.Error("bad checksum")

	// ErrEmptyPrivateKey when PK passed into WIFEncode method is nil.
	ErrEmptyPrivateKey = internal.Error("empty private key")
)

Functions

func LoadPrivateKey

func LoadPrivateKey(val string) (*ecdsa.PrivateKey, error)

LoadPrivateKey allows to load private key from various formats: - wif string - hex string - file path (D-bytes or SEC 1 / ASN.1 DER form)

func MarshalPrivateKey

func MarshalPrivateKey(key *ecdsa.PrivateKey) []byte

MarshalPrivateKey to bytes.

func MarshalPublicKey

func MarshalPublicKey(key *ecdsa.PublicKey) []byte

MarshalPublicKey to bytes.

func Sign

func Sign(key *ecdsa.PrivateKey, msg []byte) ([]byte, error)

Sign signs a message using the private key. If the sha512 hash of msg is longer than the bit-length of the private key's curve order, the hash will be truncated to that length. It returns the signature as slice bytes. The security of the private key depends on the entropy of rand.

func SignHash

func SignHash(key *ecdsa.PrivateKey, msgHash []byte) ([]byte, error)

SignHash signs message using it's hash and private key.

func SignRFC6979

func SignRFC6979(key *ecdsa.PrivateKey, msg []byte) ([]byte, error)

SignRFC6979 signs an arbitrary length hash (which should be the result of hashing a larger message) using the private key. It returns the signature as a pair of integers.

Note that FIPS 186-3 section 4.6 specifies that the hash should be truncated to the byte-length of the subgroup. This function does not perform that.

func SignRFC6979Hash

func SignRFC6979Hash(key *ecdsa.PrivateKey, msgHash []byte) ([]byte, error)

SignRFC6979Hash signs sha256 hash of the message using the private key.

func UnmarshalPrivateKey

func UnmarshalPrivateKey(data []byte) (*ecdsa.PrivateKey, error)

UnmarshalPrivateKey from bytes. It is similar to `ecdsa.Generate()` but uses pre-defined big.Int and curve for NEO Blockchain (elliptic.P256) Link - https://golang.org/pkg/crypto/ecdsa/#GenerateKey

func UnmarshalPublicKey

func UnmarshalPublicKey(data []byte) *ecdsa.PublicKey

UnmarshalPublicKey from bytes.

func Verify

func Verify(pub *ecdsa.PublicKey, msg, sig []byte) error

Verify verifies the signature of msg using the public key pub. It returns nil only if signature is valid.

func VerifyHash

func VerifyHash(pub *ecdsa.PublicKey, msgHash, sig []byte) error

VerifyHash verifies the signature of msg using it's hash the public key pub. It returns nil only if signature is valid.

func VerifyRFC6979

func VerifyRFC6979(key *ecdsa.PublicKey, msg, sig []byte) error

VerifyRFC6979 verifies the signature of msg using the public key. It return nil only if signature is valid.

func VerifyRFC6979Hash

func VerifyRFC6979Hash(key *ecdsa.PublicKey, msgHash, sig []byte) error

VerifyRFC6979 verifies the signature of msg using the public key. It return nil only if signature is valid.

func WIFDecode

func WIFDecode(wif string) (*ecdsa.PrivateKey, error)

WIFDecode decoded the given WIF string into a private key.

func WIFEncode

func WIFEncode(key *ecdsa.PrivateKey) (string, error)

WIFEncode encodes the given private key into a WIF string.