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 ¶
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 )
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 ¶
GenerateKeyPair generates a KeyPair using entropy from rng. If rng is nil, crypto/rand.Reader will be used.
func NewKeyPairFromBytes ¶
NewKeyPairFromBytes constructs a KeyPair from the byte representation.
func (*KeyPair) MarshalBinary ¶
MarshalBinary encodes a KeyPair into binary form.
func (*KeyPair) Sign ¶
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 ¶
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 ¶
NewPublicKeyFromBytes constructs a PublicKey from the byte representation.
func (*PublicKey) Equal ¶
Equal reports if pk and other have the same value. This function will execute in constant time.
func (*PublicKey) MarshalBinary ¶
MarshalBinary encodes a PublicKey into binary form.
func (*PublicKey) UnmarshalBinary ¶
UnmarshalBinary decodes a binary marshaled PublicKey.
type SecretKey ¶
type SecretKey struct {
// contains filtered or unexported fields
}
SecretKey is an expanded secret key.
func GenerateSecretKey ¶
GenerateSecretKey generates a SecretKey using entropy from rng. If rng is nil, crypto/rand.Reader will be used.
func NewSecretKeyFromBytes ¶
NewSecretKeyFromBytes constructs a SecretKey from the byte representation.
func NewSecretKeyFromEd25519Bytes ¶
NewSecretKeyFromEd25519Bytes constructs a SecretKey from the byte representation of an expanded Ed25519 key.
func (*SecretKey) Equal ¶
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) MarshalBinary ¶
MarshalBinary encodes a SecretKey into binary form.
func (*SecretKey) UnmarshalBinary ¶
UnmarshalBinary decodes a binary marshaled SecretKey.
type Signature ¶
type Signature struct {
// contains filtered or unexported fields
}
func NewSignatureFromBytes ¶
NewSignatureFromBytes constructs a Signature from the byte representation.
func (*Signature) MarshalBinary ¶
MarshalBinary encodes a Signature into binary form.
func (*Signature) UnmarshalBinary ¶
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.
Source Files