ed25519

package
v1.3.71 Latest Latest
Warning

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

 Go to latest Published: Apr 15, 2024 License: BSD-3-Clause Imports: 17 Imported by: 0

Documentation

Overview

Package ed25519 implements Ed25519 signature scheme as described in RFC-8032.

This package provides optimized implementations of the three signature variants and maintaining closer compatibility with crypto/ed25519. 

| Scheme Name | Sign Function     | Verification  | Context           |
|-------------|-------------------|---------------|-------------------|
| Ed25519     | Sign              | Verify        | None              |
| Ed25519Ph   | SignPh            | VerifyPh      | Yes, can be empty |
| Ed25519Ctx  | SignWithCtx       | VerifyWithCtx | Yes, non-empty    |
| All above   | (PrivateKey).Sign | VerifyAny     | As above          |

Specific functions for sign and verify are defined. A generic signing function for all schemes is available through the crypto.Signer interface, which is implemented by the PrivateKey type. A correspond all-in-one verification method is provided by the VerifyAny function.

Signing with Ed25519Ph or Ed25519Ctx requires a context string for domain separation. This parameter is passed using a SignerOptions struct defined in this package. While Ed25519Ph accepts an empty context, Ed25519Ctx enforces non-empty context strings.

Compatibility with crypto.ed25519

These functions are compatible with the “Ed25519” function defined in RFC-8032. However, unlike RFC 8032's formulation, this package's private key representation includes a public key suffix to make multiple signing operations with the same key more efficient. This package refers to the RFC-8032 private key as the “seed”.

References

Example (Ed25519) 
package main

import (
	"crypto/rand"
	"fmt"

	"github.com/linckode/circl/sign/ed25519"
)

func main() {
	// import "github.com/linckode/circl/sign/ed25519"
	// import "crypto/rand"

	// Generating Alice's key pair
	pub, priv, err := ed25519.GenerateKey(rand.Reader)
	if err != nil {
		panic("error on generating keys")
	}

	// Alice signs a message.
	message := []byte("A message to be signed")
	signature := ed25519.Sign(priv, message)

	// Anyone can verify the signature using Alice's public key.
	ok := ed25519.Verify(pub, message, signature)
	fmt.Println(ok)
}

Output:

true

Index

Examples

Constants

View Source 
const (
	// ContextMaxSize is the maximum length (in bytes) allowed for context.
	ContextMaxSize = 255
	// PublicKeySize is the size, in bytes, of public keys as used in this package.
	PublicKeySize = 32
	// PrivateKeySize is the size, in bytes, of private keys as used in this package.
	PrivateKeySize = 64
	// SignatureSize is the size, in bytes, of signatures generated and verified by this package.
	SignatureSize = 64
	// SeedSize is the size, in bytes, of private key seeds. These are the private key representations used by RFC 8032.
	SeedSize = 32
)

Variables

This section is empty.

Functions

func GenerateKey 

func GenerateKey(rand io.Reader) (PublicKey, PrivateKey, error)

GenerateKey generates a public/private key pair using entropy from rand. If rand is nil, crypto/rand.Reader will be used.

func Scheme 

func Scheme() sign.Scheme

Scheme returns a signature interface.

func Sign 

func Sign(privateKey PrivateKey, message []byte) []byte

Sign signs the message with privateKey and returns a signature. This function supports the signature variant defined in RFC-8032: Ed25519, also known as the pure version of EdDSA. It will panic if len(privateKey) is not PrivateKeySize.

func SignPh 

func SignPh(privateKey PrivateKey, message []byte, ctx string) []byte

SignPh creates a signature of a message with private key and context. This function supports the signature variant defined in RFC-8032: Ed25519ph, meaning it internally hashes the message using SHA-512, and optionally accepts a context string. It will panic if len(privateKey) is not PrivateKeySize. Context could be passed to this function, which length should be no more than ContextMaxSize=255. It can be empty.

Example 
package main

import (
	"crypto/rand"
	"fmt"

	"github.com/linckode/circl/sign/ed25519"
)

func main() {
	// import "github.com/linckode/circl/sign/ed25519"
	// import "crypto/rand"

	// Generating Alice's key pair
	pub, priv, err := ed25519.GenerateKey(rand.Reader)
	if err != nil {
		panic("error on generating keys")
	}

	// Alice signs a message.
	message := []byte("A message to be signed")
	ctx := "an optional context string"

	signature := ed25519.SignPh(priv, message, ctx)

	// Anyone can verify the signature using Alice's public key.
	ok := ed25519.VerifyPh(pub, message, signature, ctx)
	fmt.Println(ok)
}

Output:

true

func SignWithCtx 

func SignWithCtx(privateKey PrivateKey, message []byte, ctx string) []byte

SignWithCtx creates a signature of a message with private key and context. This function supports the signature variant defined in RFC-8032: Ed25519ctx, meaning it accepts a non-empty context string. It will panic if len(privateKey) is not PrivateKeySize. Context must be passed to this function, which length should be no more than ContextMaxSize=255 and cannot be empty.

Example 
package main

import (
	"crypto/rand"
	"fmt"

	"github.com/linckode/circl/sign/ed25519"
)

func main() {
	// import "github.com/linckode/circl/sign/ed25519"
	// import "crypto/rand"

	// Generating Alice's key pair
	pub, priv, err := ed25519.GenerateKey(rand.Reader)
	if err != nil {
		panic("error on generating keys")
	}

	// Alice signs a message.
	message := []byte("A message to be signed")
	ctx := "a non-empty context string"

	signature := ed25519.SignWithCtx(priv, message, ctx)

	// Anyone can verify the signature using Alice's public key.
	ok := ed25519.VerifyWithCtx(pub, message, signature, ctx)
	fmt.Println(ok)
}

Output:

true

func Verify 

func Verify(public PublicKey, message, signature []byte) bool

Verify returns true if the signature is valid. Failure cases are invalid signature, or when the public key cannot be decoded. This function supports the signature variant defined in RFC-8032: Ed25519, also known as the pure version of EdDSA.

func VerifyAny 

func VerifyAny(public PublicKey, message, signature []byte, opts crypto.SignerOpts) bool

VerifyAny returns true if the signature is valid. Failure cases are invalid signature, or when the public key cannot be decoded. This function supports all the three signature variants defined in RFC-8032, namely Ed25519 (or pure EdDSA), Ed25519Ph, and Ed25519Ctx. The opts.HashFunc() must return zero to specify either Ed25519 or Ed25519Ctx variant. This can be achieved by passing crypto.Hash(0) as the value for opts. The opts.HashFunc() must return SHA512 to specify the Ed25519Ph variant. This can be achieved by passing crypto.SHA512 as the value for opts. Use a SignerOptions struct to pass a context string for signing.

func VerifyPh 

func VerifyPh(public PublicKey, message, signature []byte, ctx string) bool

VerifyPh returns true if the signature is valid. Failure cases are invalid signature, or when the public key cannot be decoded. This function supports the signature variant defined in RFC-8032: Ed25519ph, meaning it internally hashes the message using SHA-512. Context could be passed to this function, which length should be no more than 255. It can be empty.

func VerifyWithCtx 

func VerifyWithCtx(public PublicKey, message, signature []byte, ctx string) bool

VerifyWithCtx returns true if the signature is valid. Failure cases are invalid signature, or when the public key cannot be decoded, or when context is not provided. This function supports the signature variant defined in RFC-8032: Ed25519ctx, meaning it does not handle prehashed messages. Non-empty context string must be provided, and must not be more than 255 of length.

Types

type PrivateKey 

type PrivateKey []byte

PrivateKey is the type of Ed25519 private keys. It implements crypto.Signer.

func NewKeyFromSeed 

func NewKeyFromSeed(seed []byte) PrivateKey

NewKeyFromSeed calculates a private key from a seed. It will panic if len(seed) is not SeedSize. This function is provided for interoperability with RFC 8032. RFC 8032's private keys correspond to seeds in this package.

func (PrivateKey) Equal 

func (priv PrivateKey) Equal(x crypto.PrivateKey) bool

Equal reports whether priv and x have the same value.

func (PrivateKey) MarshalBinary 

func (priv PrivateKey) MarshalBinary() (data []byte, err error)

func (PrivateKey) Public 

func (priv PrivateKey) Public() crypto.PublicKey

Public returns the PublicKey corresponding to priv.

func (PrivateKey) Scheme 

func (priv PrivateKey) Scheme() sign.Scheme

func (PrivateKey) Seed 

func (priv PrivateKey) Seed() []byte

Seed returns the private key seed corresponding to priv. It is provided for interoperability with RFC 8032. RFC 8032's private keys correspond to seeds in this package.

func (PrivateKey) Sign 

func (priv PrivateKey) Sign(
	rand io.Reader,
	message []byte,
	opts crypto.SignerOpts,
) (signature []byte, err error)

Sign creates a signature of a message with priv key. This function is compatible with crypto.ed25519 and also supports the three signature variants defined in RFC-8032, namely Ed25519 (or pure EdDSA), Ed25519Ph, and Ed25519Ctx. The opts.HashFunc() must return zero to specify either Ed25519 or Ed25519Ctx variant. This can be achieved by passing crypto.Hash(0) as the value for opts. The opts.HashFunc() must return SHA512 to specify the Ed25519Ph variant. This can be achieved by passing crypto.SHA512 as the value for opts. Use a SignerOptions struct (defined in this package) to pass a context string for signing.

type PublicKey 

type PublicKey cryptoEd25519.PublicKey

PublicKey is the type of Ed25519 public keys.

func (PublicKey) Equal 

func (pub PublicKey) Equal(x crypto.PublicKey) bool

Equal reports whether pub and x have the same value.

func (PublicKey) MarshalBinary 

func (pub PublicKey) MarshalBinary() (data []byte, err error)

func (PublicKey) Scheme 

func (pub PublicKey) Scheme() sign.Scheme

type SchemeID 

type SchemeID uint

SchemeID is an identifier for each signature scheme. 

const (
	ED25519 SchemeID = iota
	ED25519Ph
	ED25519Ctx
)

type SignerOptions 

type SignerOptions struct {
	// Hash must be crypto.Hash(0) for Ed25519/Ed25519ctx, or crypto.SHA512
	// for Ed25519ph.
	crypto.Hash

	// Context is an optional domain separation string for Ed25519ph and a
	// must for Ed25519ctx. Its length must be less or equal than 255 bytes.
	Context string

	// Scheme is an identifier for choosing a signature scheme. The zero value
	// is ED25519.
	Scheme SchemeID
}

SignerOptions implements crypto.SignerOpts and augments with parameters that are specific to the Ed25519 signature schemes.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.