sr25519

package
v0.0.0-...-1f23a7b Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 4, 2023 License: BSD-3-Clause Imports: 12 Imported by: 21

Documentation

Overview

Package sr25519 implements the sr25519 signature algorithm. See https://github.com/w3f/schnorrkel/.

Example

Example demonstrates common operations.

// Basic operations attempt to be similar to the w3f/schnorrkel
// Rust crate, while being as close to an idiomatic Go API as
// possible.

// Key generation

miniSecretKey, err := GenerateMiniSecretKey(rand.Reader)
if err != nil {
	panic("GenerateMiniSecretKey: " + err.Error())
}

secretKey := miniSecretKey.ExpandUniform() // ExpandEd25519 is also supported
keypair := secretKey.KeyPair()             // The KeyPair type is what is used for signing.
publicKey := keypair.PublicKey()

// Serialization

publicBytes, err := publicKey.MarshalBinary()
if err != nil {
	panic("publicKey.MarshalBinary: " + err.Error())
}

var publicKey2 PublicKey
if err = publicKey2.UnmarshalBinary(publicBytes); err != nil {
	panic("publicKey.UnmarshalBinary: " + err.Error())
}
if !publicKey.Equal(&publicKey2) {
	panic("public key did not round trip with BinaryMarshaller")
}

publicKey3, err := NewPublicKeyFromBytes(publicBytes)
if err != nil {
	panic("NewPublicKeyFromBytes: " + err.Error())
}
if !publicKey.Equal(publicKey3) {
	panic("public key did not round trip with NewPublicKeyFromBytes")
}

// Signing
signingContext := NewSigningContext([]byte("example signing context"))
msg := []byte("test message")

transcript := signingContext.NewTranscriptBytes(msg)
signature, err := keypair.Sign(rand.Reader, transcript)
if err != nil {
	panic("Sign: " + err.Error())
}

h := sha512.New512_256()
_, _ = h.Write(msg)
transcriptHashed := signingContext.NewTranscriptHash(h)
signatureHashed, err := keypair.Sign(rand.Reader, transcriptHashed)
if err != nil {
	panic("Sign(hashed): " + err.Error())
}

signatureBytes, err := signature.MarshalBinary()
if err != nil {
	panic("signature.MarshalBinary: " + err.Error())
}

signature2, err := NewSignatureFromBytes(signatureBytes)
if err != nil {
	panic("NewSignatureFromBytes: " + err.Error())
}

// Verification
//
// Note: Unlike the "other" Go sr25519 library, signing and verification
// are side-effect free, and do not alter the transcript, so the transcripts
// from the signing example are reused for brevity.

if !publicKey.Verify(transcript, signature) {
	panic("Verify failed")
}
if !publicKey.Verify(transcript, signature2) {
	panic("Verify(signature2) failed, round-trip failure?")
}

if !publicKey.Verify(transcriptHashed, signatureHashed) {
	panic("Verify(hashed) failed")
}

// This would include a (separate) batch-verification example, but the
// API is essentially identical to Ed25519, except based around transcripts.

fmt.Println("ok")
Output:

ok

Index

Examples

Constants

View Source
const (
	// MiniSecretKeySize is the size of a MiniSecretKey in bytes.
	MiniSecretKeySize = 32

	// SecretKeyScalarSize is the size of the scalar component of a
	// SecretKey in bytes.
	SecretKeyScalarSize = scalar.ScalarSize

	// SecretKeyNonceSize is the size of the nonce component of a
	// SecretKey in bytes.
	SecretKeyNonceSize = 32

	// SecretKeySize is the size of a SecretKey in bytes.
	SecretKeySize = SecretKeyScalarSize + SecretKeyNonceSize

	// PublicKeySize is the size of a PublicKey in bytes.
	PublicKeySize = curve.CompressedPointSize

	// KeyPairSize is the size of a KeyPair in bytes.
	KeyPairSize = SecretKeySize + PublicKeySize
)
View Source
const (
	// SignatureSize is the size of a sr25519 signature in bytes.
	SignatureSize = 64
)

Variables

This section is empty.

Functions

This section is empty.

Types

type BatchVerifier

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

func NewBatchVerifier

func NewBatchVerifier() *BatchVerifier

NewBatchVerifier creates an empty BatchVerifier.

func NewBatchVerifierWithCapacity

func NewBatchVerifierWithCapacity(n int) *BatchVerifier

NewBatchVerifierWithCapacity creates an empty BatchVerifier, with preallocations done for a pre-determined batch size.

func (*BatchVerifier) Add

func (v *BatchVerifier) Add(pk *PublicKey, transcript *SigningTranscript, signature *Signature)

Add adds a (public key, transcript, signature) triple to the current batch.

func (*BatchVerifier) Reset

func (v *BatchVerifier) Reset() *BatchVerifier

Reset resets a batch for reuse.

Note: This method will reuse the existing entires slice to reduce memory reallocations. If the next batch is known to be significantly smaller it may be more memory efficient to simply create a new batch.

func (*BatchVerifier) Verify

func (v *BatchVerifier) Verify(rand io.Reader) (bool, []bool)

Verify checks all entries in the current batch using entropy from rand, returning true if all entries in the current bach are valid. If one or more signature is invalid, each entry in the batch will be verified serially, and the returned bit-vector will provide information about each individual entry. If rand is nil, crypto/rand.Reader will be used.

Note: This method is only faster than individually verifying each signature if every signature is valid. That said, this method will always out-perform calling VerifyBatchOnly followed by falling back to serial verification.

func (*BatchVerifier) VerifyBatchOnly

func (v *BatchVerifier) VerifyBatchOnly(rand io.Reader) bool

VerifyBatchOnly checks all entries in the current batch using entropy from rand, returning true if all entries are valid and false if any one entry is invalid. If rand is nil, crypto/rand.Reader will be used.

If a failure arises it is unknown which entry failed, the caller must verify each entry individually.

type KeyPair

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

KeyPair encapsulates a SecretKey and PublicKey.

func GenerateKeyPair

func GenerateKeyPair(rng io.Reader) (*KeyPair, error)

GenerateKeyPair generates a KeyPair using entropy from rng. If rng is nil, crypto/rand.Reader will be used.

func NewKeyPairFromBytes

func NewKeyPairFromBytes(b []byte) (*KeyPair, error)

NewKeyPairFromBytes constructs a KeyPair from the byte representation.

func (*KeyPair) MarshalBinary

func (kp *KeyPair) MarshalBinary() ([]byte, error)

MarshalBinary encodes a KeyPair into binary form.

func (*KeyPair) PublicKey

func (kp *KeyPair) PublicKey() *PublicKey

PublicKey returns the public key component of the KeyPair.

func (*KeyPair) SecretKey

func (kp *KeyPair) SecretKey() *SecretKey

SecretKey returns the secret key component of the KeyPair.

func (*KeyPair) Sign

func (kp *KeyPair) Sign(rng io.Reader, transcript *SigningTranscript) (*Signature, error)

Sign signs a transcript with a key pair, and provided entropy source. If rng is nil, crypto/rand.Reader will be used.

func (*KeyPair) UnmarshalBinary

func (kp *KeyPair) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes a binary marshaled KeyPair.

type MiniSecretKey

type MiniSecretKey [MiniSecretKeySize]byte

MiniSecretKey is an EdDSA-like seed, from which the expanded secret key is generated.

func GenerateMiniSecretKey

func GenerateMiniSecretKey(rng io.Reader) (*MiniSecretKey, error)

GenerateMiniSecretKey generates a MiniSecretKey using entropy from rng. If rng is nil, crypto/rand.Reader will be used.

func NewMiniSecretKeyFromBytes

func NewMiniSecretKeyFromBytes(b []byte) (*MiniSecretKey, error)

NewMiniSecretKeyFromBytes constructs a MiniSecretKey from the byte representation.

func (*MiniSecretKey) Equal

func (msk *MiniSecretKey) Equal(other *MiniSecretKey) bool

Equal reports if msk and other have the same value. This function will execute in constant time.

func (*MiniSecretKey) ExpandEd25519

func (msk *MiniSecretKey) ExpandEd25519() *SecretKey

ExpandEd25519 expands a MiniSecretKey into a SecretKey using Ed25519-style bit clamping.

Note: Unless there is a specific reason to do so (eg: compatibility), the use of this method is discouraged.

func (*MiniSecretKey) ExpandUniform

func (msk *MiniSecretKey) ExpandUniform() *SecretKey

ExpandUniform expands a MiniSecretKey into a SecretKey using merlin.

func (*MiniSecretKey) MarshalBinary

func (msk *MiniSecretKey) MarshalBinary() ([]byte, error)

MarshalBinary encodes a MiniSecretKey into binary form.

func (*MiniSecretKey) UnmarshalBinary

func (msk *MiniSecretKey) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes a binary marshaled MiniSecretKey.

type PublicKey

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

PublicKey is a public key.

func NewPublicKeyFromBytes

func NewPublicKeyFromBytes(b []byte) (*PublicKey, error)

NewPublicKeyFromBytes constructs a PublicKey from the byte representation.

func (*PublicKey) Equal

func (pk *PublicKey) Equal(other *PublicKey) bool

Equal reports if pk and other have the same value. This function will execute in constant time.

func (*PublicKey) MarshalBinary

func (pk *PublicKey) MarshalBinary() ([]byte, error)

MarshalBinary encodes a PublicKey into binary form.

func (*PublicKey) UnmarshalBinary

func (pk *PublicKey) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes a binary marshaled PublicKey.

func (*PublicKey) Verify

func (pk *PublicKey) Verify(transcript *SigningTranscript, signature *Signature) bool

Verify verifies a signature by a public key on a transcript.

type SecretKey

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

SecretKey is an expanded secret key.

func GenerateSecretKey

func GenerateSecretKey(rng io.Reader) (*SecretKey, error)

GenerateSecretKey generates a SecretKey using entropy from rng. If rng is nil, crypto/rand.Reader will be used.

func NewSecretKeyFromBytes

func NewSecretKeyFromBytes(b []byte) (*SecretKey, error)

NewSecretKeyFromBytes constructs a SecretKey from the byte representation.

func NewSecretKeyFromEd25519Bytes

func NewSecretKeyFromEd25519Bytes(b []byte) (*SecretKey, error)

NewSecretKeyFromEd25519Bytes constructs a SecretKey from the byte representation of an expanded Ed25519 key.

func (*SecretKey) Equal

func (sk *SecretKey) Equal(other *SecretKey) bool

Equal reports if sk and other have the same value, where equality checks both the scalar and the nonce components. This function will execute in constant time.

func (*SecretKey) KeyPair

func (sk *SecretKey) KeyPair() *KeyPair

KeyPair returns the key pair corresponding to the SecretKey.

func (*SecretKey) MarshalBinary

func (sk *SecretKey) MarshalBinary() ([]byte, error)

MarshalBinary encodes a SecretKey into binary form.

func (*SecretKey) PublicKey

func (sk *SecretKey) PublicKey() *PublicKey

PublicKey derives the public key corresponding to the SecretKey.

func (*SecretKey) UnmarshalBinary

func (sk *SecretKey) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes a binary marshaled SecretKey.

type Signature

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

func NewSignatureFromBytes

func NewSignatureFromBytes(b []byte) (*Signature, error)

NewSignatureFromBytes constructs a Signature from the byte representation.

func (*Signature) MarshalBinary

func (sig *Signature) MarshalBinary() ([]byte, error)

MarshalBinary encodes a Signature into binary form.

func (*Signature) UnmarshalBinary

func (sig *Signature) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes a binary marshaled Signature.

type SigningContext

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

SigningContext is a Schnoor signing context.

func NewSigningContext

func NewSigningContext(context []byte) *SigningContext

NewSigningContext initializes a new signing context from a static byte string that identifies the signer's role in the larger protocol.

func (*SigningContext) NewTranscriptBytes

func (sc *SigningContext) NewTranscriptBytes(b []byte) *SigningTranscript

NewTranscriptBytes initializes a new signing transcript on a message provided as a byte array. If the length of b will overflow a 32-bit unsigned integer, this method will panic.

Note: This method should not be used for large messages as it calls merlin directly, and merlin is designed for domain separation, not performance.

func (*SigningContext) NewTranscriptHash

func (sc *SigningContext) NewTranscriptHash(h hash.Hash) *SigningTranscript

NewTranscriptHash initializes a new signing transcript on a message provided as a hash.Hash, with a digest size of either 256-bits or 512-bits. If the digest size is neither 256-bits nor 512-bits, this method will panic.

func (*SigningContext) NewTranscriptXOF

func (sc *SigningContext) NewTranscriptXOF(xof io.Reader) *SigningTranscript

NewTranscriptXOF initializes a new signing transcript on a message provided as a io.Reader that is an XOF instance.

type SigningTranscript

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

SigningTranscript is a Schnoor signing transcript.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL