ed448

Documentation

Overview

Package ed448 implements Ed448 signature scheme as described in RFC-8032.

This package implements two signature variants.

| Scheme Name | Sign Function     | Verification  | Context           |
|-------------|-------------------|---------------|-------------------|
| Ed448       | Sign              | Verify        | Yes, can be empty |
| Ed448Ph     | SignPh            | VerifyPh      | Yes, can be 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.

Both schemes require a context string for domain separation. This parameter is passed using a SignerOptions struct defined in this package.

References:

• RFC8032: https://rfc-editor.org/rfc/rfc8032.txt
• EdDSA for more curves: https://eprint.iacr.org/2015/677
• High-speed high-security signatures: https://doi.org/10.1007/s13389-012-0027-1

Example (Ed448)

package main

import (
	"crypto/rand"
	"fmt"

	"github.com/ReallyMeLabs/circl/sign/ed448"
)

func main() {
	// import "github.com/ReallyMeLabs/circl/sign/ed448"
	// import "crypto/rand"

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

	// Alice signs a message.
	message := []byte("A message to be signed")
	ctx := "This is a context string"
	signature := ed448.Sign(priv, message, ctx)

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

Output:

true

Index

• Constants
• func GenerateKey(rand io.Reader) (PublicKey, PrivateKey, error)
• func Scheme() sign.Scheme
• func Sign(priv PrivateKey, message []byte, ctx string) []byte
• func SignPh(priv PrivateKey, message []byte, ctx string) []byte
• func Verify(public PublicKey, message, signature []byte, ctx string) bool
• func VerifyAny(public PublicKey, message, signature []byte, opts crypto.SignerOpts) bool
• func VerifyPh(public PublicKey, message, signature []byte, ctx string) bool
• type PrivateKey
  • func NewKeyFromSeed(seed []byte) PrivateKey
  • func (priv PrivateKey) Equal(x crypto.PrivateKey) bool
  • func (priv PrivateKey) MarshalBinary() (data []byte, err error)
  • func (priv PrivateKey) Public() crypto.PublicKey
  • func (priv PrivateKey) Scheme() sign.Scheme
  • func (priv PrivateKey) Seed() []byte
  • 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
  • func (pub PublicKey) MarshalBinary() (data []byte, err error)
  • func (pub PublicKey) Scheme() sign.Scheme
• type SchemeID
• type SignerOptions

Examples

• Package (Ed448)
• SignPh

Constants

const (
	// ContextMaxSize is the maximum length (in bytes) allowed for context.
	ContextMaxSize = 255
	// PublicKeySize is the length in bytes of Ed448 public keys.
	PublicKeySize = 57
	// PrivateKeySize is the length in bytes of Ed448 private keys.
	PrivateKeySize = 114
	// SignatureSize is the length in bytes of signatures.
	SignatureSize = 114
	// SeedSize is the size, in bytes, of private key seeds. These are the private key representations used by RFC 8032.
	SeedSize = 57
)

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(priv PrivateKey, message []byte, ctx string) []byte

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

func SignPh

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

SignPh creates a signature of a message given a keypair. This function supports the signature variant defined in RFC-8032: Ed448ph, meaning it internally hashes the message using SHAKE-256. Context could be passed to this function, which length should be no more than 255. It can be empty.

Example

package main

import (
	"crypto/rand"
	"fmt"

	"github.com/ReallyMeLabs/circl/sign/ed448"
)

func main() {
	// import "github.com/ReallyMeLabs/circl/sign/ed448"
	// import "crypto/rand"

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

	// Alice signs a message.
	message := []byte("A message to be signed")
	ctx := "This is a context string"
	signature := ed448.SignPh(priv, message, ctx)

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

Output:

true

func Verify

func Verify(public PublicKey, message, signature []byte, ctx string) 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: Ed448, 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 two signature variants defined in RFC-8032, namely Ed448 (or pure EdDSA) and Ed448Ph. The opts.HashFunc() must return zero, this can be achieved by passing crypto.Hash(0) 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: Ed448ph, meaning it internally hashes the message using SHAKE-256. Context could be passed to this function, which length should be no more than 255. It can be empty.

Types

type PrivateKey

type PrivateKey []byte

PrivateKey is the type of Ed448 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 given a key pair. This function supports all the two signature variants defined in RFC-8032, namely Ed448 (or pure EdDSA) and Ed448Ph. The opts.HashFunc() must return zero to the specify Ed448 variant. This can be achieved by passing crypto.Hash(0) as the value for opts. Use an Options struct to pass a bool indicating that the ed448Ph variant should be used. The struct can also be optionally used to pass a context string for signing.

type PublicKey

type PublicKey []byte

PublicKey is the type of Ed448 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 (
	ED448 SchemeID = iota
	ED448Ph
)

type SignerOptions

type SignerOptions struct {
	// Hash must be crypto.Hash(0) for both Ed448 and Ed448Ph.
	crypto.Hash

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

	// Scheme is an identifier for choosing a signature scheme.
	Scheme SchemeID
}

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