bmutil

README

bmutil

[] (https://travis-ci.org/monetas/bmutil)

Package bmutil provides Bitmessage-specific convenience functions and types. A comprehensive suite of tests is provided to ensure proper functionality. Package bmutil is licensed under the liberal ISC license.

This package was developed for bmd, an alternative full-node implementation of Bitmessage which is under active development by Monetas. Although it was primarily written for bmd, this package has intentionally been designed so it can be used as a standalone package for any projects needing the functionality provided.

It is based off btcutil, which is developed by Conformal.

Documentation

[] (http://godoc.org/github.com/monetas/bmutil)

Full go doc style documentation for the project can be viewed online without installing this package by using the GoDoc site here: http://godoc.org/github.com/monetas/bmutil

You can also view the documentation locally once the package is installed with the godoc tool by running godoc -http=":6060" and pointing your browser to http://localhost:6060/pkg/github.com/monetas/bmutil

Installation

$ go get github.com/DanielKrawisz/bmutil

License

Package btcutil is licensed under the copyfree ISC License.

Documentation

Index

• Constants
• Variables
• func DecodeWIF(wif string) (*btcec.PrivateKey, error)
• func DoubleSha512(addr Address) []byte
• func EncodeWIF(privKey *btcec.PrivateKey) string
• func ReadVarBytes(r io.Reader, maxAllowed int, fieldName string) ([]byte, error)
• func ReadVarInt(r io.Reader) (uint64, error)
• func ReadVarString(r io.Reader, maxAllowed int) (string, error)
• func Sha512(addr Address) []byte
• func Tag(addr Address) *hash.Sha
• func V4BroadcastDecryptionKey(addr Address) *btcec.PrivateKey
• func V5BroadcastDecryptionKey(addr Address) *btcec.PrivateKey
• func VarIntSerializeSize(val uint64) int
• func WriteVarBytes(w io.Writer, bytes []byte) error
• func WriteVarInt(w io.Writer, val uint64) error
• func WriteVarString(w io.Writer, str string) error
• type Address
  • func DecodeAddress(addr string) (Address, error)
  • func NewAddress(version, stream uint64, ripe *hash.Ripe) (Address, error)
  • func NewDepricatedAddress(version, stream uint64, ripe *hash.Ripe) (Address, error)

Constants

const (
	// DefaultAddressVersion is the address version that we use when we
	// create new addresses.
	DefaultAddressVersion = 4

	// DefaultStream is the only stream currently in use on the Bitmessage
	// network, which is 1.
	DefaultStream = 1
)

const MaxVarIntSize = 9

MaxVarIntSize is the maximum size of a variable length integer.

Variables

var (
	// ErrChecksumMismatch describes an error where decoding failed due
	// to a bad checksum.
	ErrChecksumMismatch = errors.New("checksum mismatch")

	// ErrUnknownAddressType describes an error where an address cannot be
	// decoded as a specific address type due to the string encoding
	// begining with an invalid identifier byte or unsupported version.
	ErrUnknownAddressType = errors.New("unknown address type/version")

	// ErrDepricatedAddressVersion is returned if we try to create a
	// new address with a version less than 4.
	ErrDepricatedAddressVersion = errors.New("Address versions below 4 are depricated.")

	// ErrInvalidStream is returned if someone tries to create an address
	// with stream other than 1.
	ErrInvalidStream = errors.New("Only stream 1 is currently in use.")
)

var ErrMalformedPrivateKey = errors.New("malformed private key")

ErrMalformedPrivateKey describes an error where a WIF-encoded private key cannot be decoded due to being improperly formatted. This may occur if the byte length is incorrect or an unexpected magic number was encountered.

Functions

func DecodeWIF

func DecodeWIF(wif string) (*btcec.PrivateKey, error)

DecodeWIF creates a btcec.PrivateKey by decoding the string encoding of the import format. It only supports uncompressed keys.

The WIF string must be a base58-encoded string of the following byte sequence:

• 1 byte to identify the network, must be 0x80
• 32 bytes of a binary-encoded, big-endian, zero-padded private key
• 4 bytes of checksum, must equal the first four bytes of the double SHA256 of every byte before the checksum in this sequence

If the base58-decoded byte sequence does not match this, DecodeWIF will return a non-nil error. ErrMalformedPrivateKey is returned when the WIF is of an impossible length or the expected compressed pubkey magic number does not equal the expected value of 0x01. ErrChecksumMismatch is returned if the expected WIF checksum does not match the calculated checksum.

func DoubleSha512

func DoubleSha512(addr Address) []byte

DoubleSha512 calculates the double sha512 sum of the address, the first half of which is used as private encryption key for the public key object and the second half is used as a tag.

func EncodeWIF

func EncodeWIF(privKey *btcec.PrivateKey) string

EncodeWIF creates the Wallet Import Format string encoding of a WIF structure. See DecodeWIF for a detailed breakdown of the format and requirements of a valid WIF string.

func ReadVarBytes

func ReadVarBytes(r io.Reader, maxAllowed int,
	fieldName string) ([]byte, error)

ReadVarBytes reads a variable length byte array. A byte array is encoded as a varInt containing the length of the array followed by the bytes themselves. An error is returned if the length is greater than the passed maxAllowed parameter which helps protect against memory exhuastion attacks and forced panics thorugh malformed messages. The fieldName parameter is only used for the error message so it provides more context in the error.

func ReadVarInt

func ReadVarInt(r io.Reader) (uint64, error)

ReadVarInt reads a variable length integer from r and returns it as a uint64.

func ReadVarString

func ReadVarString(r io.Reader, maxAllowed int) (string, error)

ReadVarString reads a variable length string from r and returns it as a Go string. A varString is encoded as a varInt containing the length of the string, and the bytes that represent the string itself. An error is returned if the length is greater than the maximum block payload size, since it would not be possible to put a varString of that size into a block anyways and it also helps protect against memory exhaustion attacks and forced panics through malformed messages.

func Sha512

func Sha512(addr Address) []byte

Sha512 calculates the sha512 sum of the address, the first half of which is used as private encryption key for v2 and v3 broadcasts.

func Tag

func Tag(addr Address) *hash.Sha

Tag calculates tag corresponding to the Bitmessage address. According to protocol specifications, it is the second half of the double SHA-512 hash of version, stream and ripe concatenated together.

func V4BroadcastDecryptionKey

func V4BroadcastDecryptionKey(addr Address) *btcec.PrivateKey

V4BroadcastDecryptionKey generates the decryption private key used to decrypt v4 broadcasts originating from the address. They are encrypted with the public key corresponding to this private key as the target key. It is the first half of the SHA-512 hash of version, stream and ripe concatenated together.

func V5BroadcastDecryptionKey

func V5BroadcastDecryptionKey(addr Address) *btcec.PrivateKey

V5BroadcastDecryptionKey generates the decryption private key used to decrypt v4 pubkeys and v5 broadcasts originating from the address. Such objects are encrypted with the public key corresponding to this private key as the target key. It is the first half of the double SHA-512 hash of version, stream and ripe concatenated together.

func VarIntSerializeSize

func VarIntSerializeSize(val uint64) int

VarIntSerializeSize returns the number of bytes it would take to serialize val as a variable length integer.

func WriteVarBytes

func WriteVarBytes(w io.Writer, bytes []byte) error

WriteVarBytes serializes a variable length byte array to w as a varInt containing the number of bytes, followed by the bytes themselves.

func WriteVarInt

func WriteVarInt(w io.Writer, val uint64) error

WriteVarInt serializes val to w using a variable number of bytes depending on its value.

func WriteVarString

func WriteVarString(w io.Writer, str string) error

WriteVarString serializes str to w as a varInt containing the length of the string followed by the bytes that represent the string itself.

Types

type Address

type Address interface {
	Version() uint64
	Stream() uint64
	RipeHash() *hash.Ripe
	String() string
}

Address represents a Bitmessage address.

func DecodeAddress

func DecodeAddress(addr string) (Address, error)

DecodeAddress decodes the Bitmessage address into an Address object.

func NewAddress

func NewAddress(version, stream uint64, ripe *hash.Ripe) (Address, error)

NewAddress creates a new address. Currently supported parameters must be provided for the object to be created. That means version 4 only and stream 1.

func NewDepricatedAddress

func NewDepricatedAddress(version, stream uint64, ripe *hash.Ripe) (Address, error)

NewDepricatedAddress creates a new depricated address.