rkey

Documentation

Overview

Package rkey, short for Ripple key, implements Ripple Account Families as documented at https://ripple.com/wiki/Account_Family. This includes the ability to decode a Ripple secret key (sXXX) into the family of private and public ECDSA keys and the associated Ripple addresses.

Most types implement text marshaling (via encoding.TextMarshaler) to go to and from the Ripple base58 encoding. For example

s := new(FamilySeed);      s.UnmarshalText('sXXXX')
f := new(PublicGenerator); f.UnmarshalText('fXXXX')
p := new(AcctPrivateKey);  p.UnmarshalText('pXXXX')
a := new(AcctPublicKey);   a.UnmarshalText('aXXXX')

GenerateSeed can be used to generate a new random FamilySeed and get the matching keys and Ripple address.

The types are structured like the following pseudo-code:

FamilySeed struct {
    Seed: 128 bit random number, encoded as sXXX
    PrivateGenerator struct {
        D
        PublicGenerator struct {
             X, Y: encoded as fXXX (from the compressed point)
        }
    }
}
PrivateGenerator.Generate(int) -> AcctPrivateKey, encoded as pXXX
PublicGenerator.Generate(int)  -> AcctPublicKey,  encoded as aXXX

Thus creating a FamilySeed also creates the generators. It's also possible to create and use just a PublicGenerator or just an AcctPublicKey without knowing the FamilySeed, PrivateGenerator, etc.

TODO(dchapes): Currently all types implement Key which is an exported interface. This probably shouldn't be exported and ideally a better/cleaner implementation would be used.

Example (Address)

package main

import (
	"bitbucket.org/dchapes/ripple/crypto/rkey"
	"fmt"
)

const secret = "sp6JS7f14BuwFY8Mw6bTtLKWauoUs"

func main() {
	s, _ := rkey.NewFamilySeed(secret)
	pubkey := s.PrivateGenerator.PublicGenerator.Generate(0)
	addr := pubkey.Address()
	fmt.Println("secret:", secret, "address:", addr)
}

Output:

secret: sp6JS7f14BuwFY8Mw6bTtLKWauoUs address: rJq5ce8cdbWBsysXx32rvLMV6DUxMwruMT

Index

• type AccountId
  • func NewAccountId(text string) (*AccountId, error)
  • func (r *AccountId) MarshalText() ([]byte, error)
  • func (r *AccountId) UnmarshalText(text []byte) error
• type AcctPrivateKey
  • func NewAcctPrivateKey(text string) (*AcctPrivateKey, error)
  • func (p *AcctPrivateKey) MarshalText() ([]byte, error)
  • func (p *AcctPrivateKey) UnmarshalText(text []byte) error
• type AcctPublicKey
  • func NewAcctPublicKey(text string) (*AcctPublicKey, error)
  • func (p *AcctPublicKey) AccountId() *AccountId
  • func (p *AcctPublicKey) Address() string
  • func (p *AcctPublicKey) MarshalJSON() ([]byte, error)
  • func (a *AcctPublicKey) MarshalText() ([]byte, error)
  • func (p *AcctPublicKey) UnmarshalJSON(in []byte) error
  • func (a *AcctPublicKey) UnmarshalText(text []byte) error
• type FamilySeed
  • func GenerateSeed() (*FamilySeed, error)
  • func NewFamilySeed(text string) (*FamilySeed, error)
  • func NewSeed(i *big.Int) (*FamilySeed, error)
  • func (s *FamilySeed) MarshalText() ([]byte, error)
  • func (s *FamilySeed) UnmarshalText(text []byte) error
• type Key
  • func New(text string) (Key, error)
• type PrivateGenerator
  • func (g *PrivateGenerator) Generate(idx uint32) *AcctPrivateKey
• type PublicGenerator
  • func NewPublicGenerator(text string) (*PublicGenerator, error)
  • func (g *PublicGenerator) Generate(idx uint32) *AcctPublicKey
  • func (f *PublicGenerator) MarshalText() ([]byte, error)
  • func (f *PublicGenerator) UnmarshalText(text []byte) error

Examples

• Package (Address)

Types

type AccountId

type AccountId struct {
	Id *big.Int
}

An AccountId is a hash of a public key.

Its Ripple base58 encoding starts with `r` as is the Ripple address.

TODO(dchapes): remove?

func NewAccountId

func NewAccountId(text string) (*AccountId, error)

func (*AccountId) MarshalText

func (r *AccountId) MarshalText() ([]byte, error)

func (*AccountId) UnmarshalText

func (r *AccountId) UnmarshalText(text []byte) error

type AcctPrivateKey

type AcctPrivateKey ecdsa.PrivateKey

An AcctPrivateKey is a specific ECDSA private key within an account family.

Its Ripple base58 encoding starts with `p`.

func NewAcctPrivateKey

func NewAcctPrivateKey(text string) (*AcctPrivateKey, error)

func (*AcctPrivateKey) MarshalText

func (p *AcctPrivateKey) MarshalText() ([]byte, error)

func (*AcctPrivateKey) UnmarshalText

func (p *AcctPrivateKey) UnmarshalText(text []byte) error

type AcctPublicKey

type AcctPublicKey ecdsa.PublicKey

An AcctPublicKey is a specific ECDSA public key within an account family.

Its Ripple base58 encoding starts with `a`.

func NewAcctPublicKey

func NewAcctPublicKey(text string) (*AcctPublicKey, error)

func (*AcctPublicKey) AccountId

func (p *AcctPublicKey) AccountId() *AccountId

AccountId returns the account id (aka Ripple address) for this public key.

TODO(dchapes): remove?

func (*AcctPublicKey) Address

func (p *AcctPublicKey) Address() string

Address returns the Ripple address of this public key.

func (*AcctPublicKey) MarshalJSON

func (p *AcctPublicKey) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface. Ripple uses a DER style encoding in JSON Ripple transactions rather than base58 encoding.

func (*AcctPublicKey) MarshalText

func (a *AcctPublicKey) MarshalText() ([]byte, error)

func (*AcctPublicKey) UnmarshalJSON

func (p *AcctPublicKey) UnmarshalJSON(in []byte) error

UnmarshalJSON implements the json.Unmarshaler interface. Ripple uses a DER style encoding in JSON Ripple transactions rather than base58 encoding.

func (*AcctPublicKey) UnmarshalText

func (a *AcctPublicKey) UnmarshalText(text []byte) error

type FamilySeed

type FamilySeed struct {
	Seed *big.Int
	PrivateGenerator
}

A FamilySeed, also called the Ripple secret, is a 128 bit random number used to generate all the private keys, public keys, and Ripple addresses within the account family.

Its Ripple base58 encoding starts with `s`.

func GenerateSeed

func GenerateSeed() (*FamilySeed, error)

GenerateSeed uses crypto/rand to generate a new random FamilySeed.

func NewFamilySeed

func NewFamilySeed(text string) (*FamilySeed, error)

func NewSeed

func NewSeed(i *big.Int) (*FamilySeed, error)

NewSeed uses the provided Int, which must be <=128 bits long, as a FamilySeed.

func (*FamilySeed) MarshalText

func (s *FamilySeed) MarshalText() ([]byte, error)

func (*FamilySeed) UnmarshalText

func (s *FamilySeed) UnmarshalText(text []byte) error

type Key

type Key interface {
	encoding.TextMarshaler
	encoding.TextUnmarshaler
	// contains filtered or unexported methods
}

Key is ??? TODO(dchapes): should this even be exported? Is there a better/cleaner way to implement this.

func New

func New(text string) (Key, error)

New returns a new Key decoded from a Ripple base58 encoded text.

type PrivateGenerator

type PrivateGenerator struct {
	D *big.Int
	PublicGenerator
}

A PrivateGenerator, also called the root private key or master private key, is effectively a ECDSA private key used to make the PrivateGenerator (the matching ECDSA public key) and the individual AcctPrivateKey's within the account family.

With the private generator, all the private keys can be determined.

func (*PrivateGenerator) Generate

func (g *PrivateGenerator) Generate(idx uint32) *AcctPrivateKey

Generate is used to generate the AcctPrivateKey for sequence idx in this account family.

type PublicGenerator

type PublicGenerator struct {
	X, Y *big.Int
}

A PublicGenerator, also called the root/master public key or family generator, is effectively a ECDSA public key used to make the individual AcctPublicKey's within the account family.

The PublicGenerator is so named because it generates the public keys, not because it should be made public.

With the public generator, anyone can determine which accounts are in the family.

Caution: With the public generator and any one private key, the private generator can be determined. For this reason, export of individual private keys should not be allowed when the accounts are part of a family.

Its Ripple base58 encoding starts with `f`

func NewPublicGenerator

func NewPublicGenerator(text string) (*PublicGenerator, error)

func (*PublicGenerator) Generate

func (g *PublicGenerator) Generate(idx uint32) *AcctPublicKey

Generate is used to generate the AcctPublicKey for sequence idx in this account family.

func (*PublicGenerator) MarshalText

func (f *PublicGenerator) MarshalText() ([]byte, error)

func (*PublicGenerator) UnmarshalText

func (f *PublicGenerator) UnmarshalText(text []byte) error