irohasign

README

irohasign

Pure-Go library for building and signing Hyperledger Iroha v1 protobuf transactions — grant-permission commands, asset transfers, and atomic batches.

Why

Iroha uses SHA3-512 everywhere plain Ed25519 uses SHA-512, so Go's stdlib crypto/ed25519 can't produce a valid signature against a real Iroha node. keypair.go/sign.go reimplement the construction by hand with filippo.io/edwards25519, cross-checked byte-for-byte against known-answer vectors from iroha-java — see *_test.go.

What's here

• keypair.go — key generation, hex encode/decode
• sign.go — the Ed25519-SHA3 signing primitive
• hash.go — reduced hash and full transaction hash
• transaction.go — a builder mirroring iroha-java's chain (GrantPermission, TransferAsset, batch re-signing)
• proto/ — generated bindings for the Iroha proto subset this package needs; regenerate with make proto

Usage

kp, err := irohasign.GenerateKeyPair()

b := irohasign.NewTransactionBuilder(accountID, createdTimeMs).
    GrantPermission(granteeAccountID, irohapb.GrantablePermission_can_add_my_signatory)

reducedHash, err := b.ReducedHashHex() // e.g. for a draft/pre-register step
tx, err := b.Sign(kp)
txBytes, err := proto.Marshal(tx)

// Re-sign an already-built transaction as part of an ATOMIC batch, once
// the other reduced hashes in the batch are known:
resigned, err := irohasign.ReSignWithBatchMeta(txBytes, kp, []string{
    reducedHash, otherReducedHash1, otherReducedHash2,
})

Development

make test    # run tests
make lint    # run golangci-lint
make proto   # regenerate proto/*.pb.go
make setup   # install tools and git hooks

Documentation

Overview

Package irohasign signs Iroha v1 transactions with Ed25519-SHA3 (SHA3-512 in place of SHA-512), incompatible with stdlib crypto/ed25519.

Index

• func FullHash(payload *irohapb.Transaction_Payload) ([]byte, error)
• func ReSignWithBatchMeta(transactionBytes []byte, kp KeyPair, reducedHashesHex []string) (*irohapb.Transaction, error)
• func ReducedHash(reducedPayload *irohapb.Transaction_Payload_ReducedPayload) ([]byte, error)
• type KeyPair
  • func GenerateKeyPair() (KeyPair, error)
  • func KeyPairFromHex(publicHex, privateHex string) (KeyPair, error)
  • func (kp KeyPair) PrivateHex() string
  • func (kp KeyPair) PublicHex() string
  • func (kp KeyPair) Sign(message []byte) ([]byte, error)
• type TransactionBuilder
  • func NewTransactionBuilder(creatorAccountID string, createdTimeUnixMillis uint64) *TransactionBuilder
  • func (b *TransactionBuilder) GrantPermission(accountID string, permission irohapb.GrantablePermission) *TransactionBuilder
  • func (b *TransactionBuilder) ReducedHash() ([]byte, error)
  • func (b *TransactionBuilder) ReducedHashHex() (string, error)
  • func (b *TransactionBuilder) SetQuorum(quorum uint32) *TransactionBuilder
  • func (b *TransactionBuilder) Sign(kp KeyPair) (*irohapb.Transaction, error)
  • func (b *TransactionBuilder) SignWithBatchMeta(kp KeyPair, reducedHashesHex []string) (*irohapb.Transaction, error)
  • func (b *TransactionBuilder) TransferAsset(srcAccountID, destAccountID, assetID, description, amount string) *TransactionBuilder

Functions

func FullHash

func FullHash(payload *irohapb.Transaction_Payload) ([]byte, error)

FullHash hashes the whole Payload — iroha-java's Utils.hash / toHexHash. This is also the message that gets signed, not the raw payload; see Transaction.sign in transaction.go.

func ReSignWithBatchMeta

func ReSignWithBatchMeta(transactionBytes []byte, kp KeyPair, reducedHashesHex []string) (*irohapb.Transaction, error)

ReSignWithBatchMeta re-signs a built transaction with ATOMIC batch metadata known only after a first round trip.

func ReducedHash

func ReducedHash(reducedPayload *irohapb.Transaction_Payload_ReducedPayload) ([]byte, error)

ReducedHash hashes ReducedPayload alone, excluding batch metadata — iroha-java's Utils.reducedHash.

Types

type KeyPair

type KeyPair struct {
	Seed      [32]byte
	PublicKey [32]byte
}

KeyPair is an Iroha Ed25519-SHA3 key pair: a 32-byte seed and public key.

func GenerateKeyPair

func GenerateKeyPair() (KeyPair, error)

GenerateKeyPair creates a new random key pair.

func KeyPairFromHex

func KeyPairFromHex(publicHex, privateHex string) (KeyPair, error)

KeyPairFromHex parses a hex-encoded public key and seed, as produced by AccountRecord.publicKey/privateKey.

func (KeyPair) PrivateHex

func (kp KeyPair) PrivateHex() string

PrivateHex is the lowercase hex encoding of the raw seed, not an expanded 64-byte secret key.

func (KeyPair) PublicHex

func (kp KeyPair) PublicHex() string

PublicHex is the lowercase hex encoding of the public key — iroha-java's Utils.toHex(...).toLowerCase().

func (KeyPair) Sign

func (kp KeyPair) Sign(message []byte) ([]byte, error)

Sign produces a 64-byte Ed25519-SHA3 signature (R || S) over message.

type TransactionBuilder

type TransactionBuilder struct {
	// contains filtered or unexported fields
}

TransactionBuilder mirrors iroha-java's builder chain; only GrantPermission and TransferAsset commands are implemented so far.

func NewTransactionBuilder

func NewTransactionBuilder(creatorAccountID string, createdTimeUnixMillis uint64) *TransactionBuilder

NewTransactionBuilder starts a transaction with an explicit created-time (Unix ms) — reuse it for any later re-hash or re-sign.

func (*TransactionBuilder) GrantPermission

func (b *TransactionBuilder) GrantPermission(accountID string, permission irohapb.GrantablePermission) *TransactionBuilder

GrantPermission appends a GrantPermission command.

func (*TransactionBuilder) ReducedHash

func (b *TransactionBuilder) ReducedHash() ([]byte, error)

ReducedHash returns the SHA3-256 reduced-payload hash, unsigned — payment-service's grantPermissionReducedHash.

func (*TransactionBuilder) ReducedHashHex

func (b *TransactionBuilder) ReducedHashHex() (string, error)

ReducedHashHex is ReducedHash, hex-encoded uppercase like iroha-java's Utils.toHex.

func (*TransactionBuilder) SetQuorum

func (b *TransactionBuilder) SetQuorum(quorum uint32) *TransactionBuilder

SetQuorum overrides this transaction's default quorum of 1 (signatures required).

func (*TransactionBuilder) Sign

func (b *TransactionBuilder) Sign(kp KeyPair) (*irohapb.Transaction, error)

Sign finalizes and signs a standalone (non-batched) transaction.

func (*TransactionBuilder) SignWithBatchMeta

func (b *TransactionBuilder) SignWithBatchMeta(kp KeyPair, reducedHashesHex []string) (*irohapb.Transaction, error)

SignWithBatchMeta signs as part of an ATOMIC batch; include this transaction's own ReducedHashHex in reducedHashesHex.

func (*TransactionBuilder) TransferAsset

func (b *TransactionBuilder) TransferAsset(srcAccountID, destAccountID, assetID, description, amount string) *TransactionBuilder

TransferAsset appends a TransferAsset command.