ed25519

Documentation

Overview

Package ed25519 implements the Ed25519 signature algorithm. See https://ed25519.cr.yp.to/.

This package stores the private key in the NaCl format, which is a different format than that used by the crypto/ed25519 package in the standard library.

This picture will help with the rest of the explanation: https://blog.mozilla.org/warner/files/2011/11/key-formats.png

The private key in the crypto/ed25519 package is a 64-byte value where the first 32-bytes are the seed and the last 32-bytes are the public key.

The private key in this package is stored in the NaCl format. That is, the left 32-bytes are the private scalar A and the right 32-bytes are the right half of the SHA512 result.

The contents of this package are mostly copied from the standard library, and as such the source code is licensed under the BSD license of the standard library implementation.

Other notable changes from the standard library include:

• The Seed function of the standard library is not implemented in this package because there is no way to recover the seed after hashing it.

Index

• Constants
• func GenerateKey(rand io.Reader) (PublicKey, PrivateKey, error)
• func Sign(privateKey PrivateKey, message []byte) []byte
• func Verify(publicKey PublicKey, message, sig []byte) bool
• func VerifyWithOptions(publicKey PublicKey, message, sig []byte, opts *Options) error
• type Options
  • func (o *Options) HashFunc() crypto.Hash
• type PrivateKey
  • func NewKeyFromSeed(seed []byte) PrivateKey
  • func (priv PrivateKey) Equal(x crypto.PrivateKey) bool
  • func (priv PrivateKey) Public() crypto.PublicKey
  • func (priv PrivateKey) Sign(rand io.Reader, message []byte, opts crypto.SignerOpts) (signature []byte, err error)
• type PublicKey
  • func (pub PublicKey) Equal(x crypto.PublicKey) bool

Constants

const (
	// 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
)

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.

The output of this function is deterministic, and equivalent to reading SeedSize bytes from rand, and passing them to NewKeyFromSeed.

func Sign

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

Sign signs the message with privateKey and returns a signature. It will panic if len(privateKey) is not PrivateKeySize.

func Verify

func Verify(publicKey PublicKey, message, sig []byte) bool

Verify reports whether sig is a valid signature of message by publicKey. It will panic if len(publicKey) is not PublicKeySize.

This is just a wrapper around ed25519.Verify from the standard library.

func VerifyWithOptions

func VerifyWithOptions(publicKey PublicKey, message, sig []byte, opts *Options) error

VerifyWithOptions reports whether sig is a valid signature of message by publicKey. A valid signature is indicated by returning a nil error. It will panic if len(publicKey) is not PublicKeySize.

If opts.Hash is crypto.SHA512, the pre-hashed variant Ed25519ph is used and message is expected to be a SHA-512 hash, otherwise opts.Hash must be crypto.Hash(0) and the message must not be hashed, as Ed25519 performs two passes over messages to be signed.

This is just a wrapper around ed25519.VerifyWithOptions from the standard library.

Types

type Options

type Options struct {
	// Hash can be zero for regular Ed25519, or crypto.SHA512 for Ed25519ph.
	Hash crypto.Hash

	// Context, if not empty, selects Ed25519ctx or provides the context string
	// for Ed25519ph. It can be at most 255 bytes in length.
	Context string
}

Options can be used with PrivateKey.Sign or VerifyWithOptions to select Ed25519 variants.

func (*Options) HashFunc

func (o *Options) HashFunc() crypto.Hash

HashFunc returns o.Hash.

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) Public

func (priv PrivateKey) Public() crypto.PublicKey

Public returns the PublicKey corresponding to priv.

This method differs from the standard library because it calculates the public key instead of returning the right half of the private key (which contains the public key in the standard library).

func (PrivateKey) Sign

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

Sign signs the given message with priv. rand is ignored and can be nil.

If opts.HashFunc() is crypto.SHA512, the pre-hashed variant Ed25519ph is used and message is expected to be a SHA-512 hash, otherwise opts.HashFunc() must be crypto.Hash(0) and the message must not be hashed, as Ed25519 performs two passes over messages to be signed.

A value of type Options can be used as opts, or crypto.Hash(0) or crypto.SHA512 directly to select plain Ed25519 or Ed25519ph, respectively.

type PublicKey

type PublicKey []byte

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.