crypto

README

crypto

crypto is the cryptographic package adapted for CometBFT's uses

Importing it

To get the interfaces, import "github.com/cometbft/cometbft/crypto"

For any specific algorithm, use its specific module e.g. import "github.com/cometbft/cometbft/crypto/ed25519"

Binary encoding

For Binary encoding, please refer to the CometBFT encoding specification.

JSON Encoding

JSON encoding is done using CometBFT's internal json encoder. For more information on JSON encoding, please refer to CometBFT JSON encoding

Example JSON encodings:

ed25519.PrivKey     - {"type":"tendermint/PrivKeyEd25519","value":"EVkqJO/jIXp3rkASXfh9YnyToYXRXhBr6g9cQVxPFnQBP/5povV4HTjvsy530kybxKHwEi85iU8YL0qQhSYVoQ=="}
ed25519.PubKey      - {"type":"tendermint/PubKeyEd25519","value":"AT/+aaL1eB0477Mud9JMm8Sh8BIvOYlPGC9KkIUmFaE="}
crypto.PrivKeySecp256k1   - {"type":"tendermint/PrivKeySecp256k1","value":"zx4Pnh67N+g2V+5vZbQzEyRerX9c4ccNZOVzM9RvJ0Y="}
crypto.PubKeySecp256k1    - {"type":"tendermint/PubKeySecp256k1","value":"A8lPKJXcNl5VHt1FK8a244K9EJuS4WX1hFBnwisi0IJx"}

Documentation

Overview

crypto is a customized/convenience cryptography package for CometBFT.

It wraps select functionality of equivalent functions in the Go standard library, for easy usage with our libraries.

Keys:

All key generation functions return an instance of the PrivKey interface which implements methods:

type PrivKey interface {
	Bytes() []byte
	Sign(msg []byte) ([]byte, error)
	PubKey() PubKey
	Type() string
}

From the above method we can retrieve the public key if needed:

privKey, err := ed25519.GenPrivKey()
if err != nil {
	panic(err)
}
pubKey := privKey.PubKey()

The resulting public key is an instance of the PubKey interface:

type PubKey interface {
	Address() Address
	Bytes() []byte
	VerifySignature(msg []byte, sig []byte) bool
	Type() string
}

Index

• Constants
• func CRandBytes(numBytes int) []byte
• func CRandHex(numDigits int) string
• func CReader() io.Reader
• func Sha256(bytes []byte) []byte
• type Address
  • func AddressHash(bz []byte) Address
• type BatchVerifier
• type PrivKey
• type PubKey
• type Symmetric

Examples

• Sha256

Constants

const (
	// AddressSize is the size of a pubkey address.
	AddressSize = tmhash.TruncatedSize
)

const Version = "0.9.0-dev"

Functions

func CRandBytes

func CRandBytes(numBytes int) []byte

This only uses the OS's randomness.

func CRandHex

func CRandHex(numDigits int) string

CRandHex returns a hex encoded string that's floor(numDigits/2) * 2 long.

Note: CRandHex(24) gives 96 bits of randomness that are usually strong enough for most purposes.

func CReader

func CReader() io.Reader

Returns a crand.Reader.

func Sha256

func Sha256(bytes []byte) []byte

Example

package main

import (
	"fmt"

	"github.com/cometbft/cometbft/crypto"
)

func main() {
	sum := crypto.Sha256([]byte("This is CometBFT"))
	fmt.Printf("%x\n", sum)
}

Output:

ea186526b041852d923b02c91aa04b00c0df258b3d69cb688eaba577f5562758

Types

type Address

type Address = bytes.HexBytes

An address is a []byte, but hex-encoded even in JSON. []byte leaves us the option to change the address length. Use an alias so Unmarshal methods (with ptr receivers) are available too.

func AddressHash

func AddressHash(bz []byte) Address

type BatchVerifier

type BatchVerifier interface {
	// Add appends an entry into the BatchVerifier.
	Add(key PubKey, message, signature []byte) error
	// Verify verifies all the entries in the BatchVerifier, and returns
	// if every signature in the batch is valid, and a vector of bools
	// indicating the verification status of each signature (in the order
	// that signatures were added to the batch).
	Verify() (bool, []bool)
}

If a new key type implements batch verification, the key type must be registered in github.com/cometbft/cometbft/crypto/batch.

type PrivKey

type PrivKey interface {
	Bytes() []byte
	Sign(msg []byte) ([]byte, error)
	PubKey() PubKey
	Type() string
}

type PubKey

type PubKey interface {
	Address() Address
	Bytes() []byte
	VerifySignature(msg []byte, sig []byte) bool
	Type() string
}

type Symmetric

type Symmetric interface {
	Keygen() []byte
	Encrypt(plaintext []byte, secret []byte) (ciphertext []byte)
	Decrypt(ciphertext []byte, secret []byte) (plaintext []byte, err error)
}