ed25519ph

README

ed25519ph

-- import "github.com/go-i2p/crypto/ed25519ph"

Package ed25519ph provides Ed25519ph (pre-hashed) digital signature functionality.

Ed25519ph is the pre-hashed variant of Ed25519 defined in RFC 8032 §5.1. Unlike PureEdDSA (standard Ed25519), Ed25519ph hashes the message with SHA-512 before signing, using a domain separation tag to distinguish signatures from PureEdDSA. This makes Ed25519ph suitable for signing large messages or when the signer cannot buffer the entire message before signing.

IMPORTANT: Ed25519ph signatures are NOT interchangeable with standard Ed25519 (PureEdDSA) signatures. An Ed25519ph signature cannot be verified by a PureEdDSA verifier and vice versa, even though both use the same key format.

For standard I2P Ed25519 signatures (signature type 7: EdDSA-SHA512-Ed25519), use the ed25519 package instead.

Ed25519 vs Ed25519ph

Property	Ed25519 (PureEdDSA)	Ed25519ph (Pre-hashed)
RFC 8032 mode	Pure	Pre-hashed (§5.1)
Pre-hash	None (internal SHA-512)	External SHA-512 + domain sep
I2P sig type 7	✅ Yes	❌ No
Interoperable	With Java I2P, i2pd	Only with other Ed25519ph
Use case	Standard I2P signatures	Large messages, streaming

Usage

// Generate a key pair
pubKey, privKey, err := ed25519ph.GenerateEd25519phKeyPair()
if err != nil {
    return err
}
defer privKey.Zero()

// Sign data
signer, _ := privKey.NewSigner()
sig, err := signer.Sign(data)

// Verify data
verifier, _ := pubKey.NewVerifier()
err = verifier.Verify(data, sig)

Types

type Ed25519phPublicKey

type Ed25519phPublicKey []byte

Ed25519phPublicKey represents an Ed25519 public key for Ed25519ph signature verification. The key format is identical to standard Ed25519 (32 bytes).

type Ed25519phPrivateKey

type Ed25519phPrivateKey ed25519.PrivateKey

Ed25519phPrivateKey represents an Ed25519 private key for Ed25519ph signature operations. The key format is identical to standard Ed25519 (64 bytes).

type Ed25519phSigner

type Ed25519phSigner struct{}

Ed25519phSigner provides digital signature creation using the Ed25519ph (pre-hashed) variant defined in RFC 8032 §5.1.

type Ed25519phVerifier

type Ed25519phVerifier struct{}

Ed25519phVerifier provides digital signature verification using the Ed25519ph (pre-hashed) variant defined in RFC 8032 §5.1.

Functions

func GenerateEd25519phKey

func GenerateEd25519phKey() (types.SigningPrivateKey, error)

GenerateEd25519phKey generates a new Ed25519 private key for Ed25519ph signatures.

func GenerateEd25519phKeyPair

func GenerateEd25519phKeyPair() (*Ed25519phPublicKey, *Ed25519phPrivateKey, error)

GenerateEd25519phKeyPair generates a new Ed25519 key pair for Ed25519ph signatures. This is the recommended API.

func NewEd25519phPublicKey

func NewEd25519phPublicKey(data []byte) (Ed25519phPublicKey, error)

NewEd25519phPublicKey creates a validated Ed25519ph public key from bytes.

func NewEd25519phPrivateKey

func NewEd25519phPrivateKey(data []byte) (Ed25519phPrivateKey, error)

NewEd25519phPrivateKey creates a validated Ed25519ph private key from bytes.

Documentation

Overview

Package ed25519ph provides Ed25519ph (pre-hashed) digital signature functionality.

Ed25519ph is the pre-hashed variant of Ed25519 defined in RFC 8032 §5.1. Unlike PureEdDSA (standard Ed25519), Ed25519ph hashes the message with SHA-512 before signing, using a domain separation tag to distinguish signatures from PureEdDSA. This makes Ed25519ph suitable for signing large messages or when the signer cannot buffer the entire message before signing.

IMPORTANT: Ed25519ph signatures are NOT interchangeable with standard Ed25519 (PureEdDSA) signatures. An Ed25519ph signature cannot be verified by a PureEdDSA verifier and vice versa, even though both use the same key format.

For standard I2P Ed25519 signatures (signature type 7: EdDSA-SHA512-Ed25519), use the ed25519 package instead. This package exists for applications that specifically require the pre-hashed variant.

Index

• Variables
• func GenerateEd25519phKey() (types.SigningPrivateKey, error)
• func GenerateEd25519phKeyPair() (*Ed25519phPublicKey, *Ed25519phPrivateKey, error)
• type Ed25519phPrivateKey
  • func NewEd25519phPrivateKey(data []byte) (Ed25519phPrivateKey, error)
  • func (k Ed25519phPrivateKey) Bytes() []byte
  • func (k Ed25519phPrivateKey) Generate() (types.SigningPrivateKey, error)
  • func (k Ed25519phPrivateKey) Len() int
  • func (k Ed25519phPrivateKey) NewSigner() (types.Signer, error)
  • func (k *Ed25519phPrivateKey) NewVerifier() (types.Verifier, error)
  • func (k Ed25519phPrivateKey) Public() (types.SigningPublicKey, error)
  • func (k Ed25519phPrivateKey) Zero()
• type Ed25519phPublicKey
  • func NewEd25519phPublicKey(data []byte) (Ed25519phPublicKey, error)
  • func (k Ed25519phPublicKey) Bytes() []byte
  • func (k Ed25519phPublicKey) Len() int
  • func (k Ed25519phPublicKey) NewVerifier() (v types.Verifier, err error)
• type Ed25519phSigner
  • func (s *Ed25519phSigner) Sign(data []byte) (sig []byte, err error)
  • func (s *Ed25519phSigner) SignHash(h []byte) (sig []byte, err error)
• type Ed25519phVerifier
  • func (v *Ed25519phVerifier) Verify(data, sig []byte) (err error)
  • func (v *Ed25519phVerifier) VerifyHash(h, sig []byte) (err error)

Variables

var (
	// ErrInvalidPublicKeySize indicates an Ed25519 public key does not meet the required 32-byte size.
	ErrInvalidPublicKeySize = oops.Errorf("failed to verify: invalid ed25519ph public key size")

	// ErrInvalidPrivateKeySize indicates an Ed25519 private key does not meet the required 64-byte size.
	ErrInvalidPrivateKeySize = oops.Errorf("invalid ed25519ph private key size")
)

Error constants for Ed25519ph operations.

Functions

func GenerateEd25519phKey

func GenerateEd25519phKey() (types.SigningPrivateKey, error)

GenerateEd25519phKey generates a new Ed25519 private key for Ed25519ph signatures. This function creates a cryptographically secure Ed25519 keypair using the system's random number generator. The returned private key implements the SigningPrivateKey interface and produces Ed25519ph (pre-hashed) signatures with domain separation per RFC 8032.

func GenerateEd25519phKeyPair

func GenerateEd25519phKeyPair() (*Ed25519phPublicKey, *Ed25519phPrivateKey, error)

GenerateEd25519phKeyPair generates a new Ed25519 key pair for Ed25519ph signatures. This is the recommended API for generating Ed25519ph keys, returning concrete types directly without interface conversions.

Returns:

• *Ed25519phPublicKey: The public key for Ed25519ph signature verification
• *Ed25519phPrivateKey: The private key for Ed25519ph signing (must be zeroed after use)
• error: Any error that occurred during key generation

Example:

pubKey, privKey, err := ed25519ph.GenerateEd25519phKeyPair()
if err != nil {
    return err
}
defer privKey.Zero()

Types

type Ed25519phPrivateKey

type Ed25519phPrivateKey ed25519.PrivateKey

Ed25519phPrivateKey represents an Ed25519 private key for Ed25519ph signature operations. The key format is identical to standard Ed25519 (64 bytes), but the signing algorithm uses pre-hashing with SHA-512 and domain separation per RFC 8032 §5.1.

CRITICAL: Always use NewEd25519phPrivateKey() to create instances.

Security:

• Private keys contain sensitive material
• Always call Zero() when done to clear memory
• Never log or transmit private keys

func NewEd25519phPrivateKey

func NewEd25519phPrivateKey(data []byte) (Ed25519phPrivateKey, error)

NewEd25519phPrivateKey creates a validated Ed25519ph private key from bytes. This is the REQUIRED constructor.

Parameters:

• data: Must be exactly 64 bytes

Returns error if data length is invalid.

func (Ed25519phPrivateKey) Bytes

func (k Ed25519phPrivateKey) Bytes() []byte

Bytes returns the raw byte representation of the Ed25519ph private key. The returned slice contains the full 64-byte Ed25519 private key including the embedded public key portion.

func (Ed25519phPrivateKey) Generate

func (k Ed25519phPrivateKey) Generate() (types.SigningPrivateKey, error)

Generate creates a new random Ed25519 private key for use with Ed25519ph. This method generates a fresh keypair and returns it as a SigningPrivateKey interface.

func (Ed25519phPrivateKey) Len

func (k Ed25519phPrivateKey) Len() int

Len returns the length of the Ed25519ph private key in bytes. Ed25519 private keys are always 64 bytes long.

func (Ed25519phPrivateKey) NewSigner

func (k Ed25519phPrivateKey) NewSigner() (types.Signer, error)

NewSigner creates a new Ed25519ph signer instance for generating pre-hashed signatures. Returns a signer that creates Ed25519ph signatures with domain separation per RFC 8032.

func (*Ed25519phPrivateKey) NewVerifier

func (k *Ed25519phPrivateKey) NewVerifier() (types.Verifier, error)

NewVerifier creates a verifier instance from this private key's public component. This method extracts the public key and returns an Ed25519ph verifier that can validate signatures created by this private key.

func (Ed25519phPrivateKey) Public

func (k Ed25519phPrivateKey) Public() (types.SigningPublicKey, error)

Public extracts the Ed25519 public key from this private key. Returns the corresponding public key for Ed25519ph signature verification.

func (Ed25519phPrivateKey) Zero

func (k Ed25519phPrivateKey) Zero()

Zero securely clears the private key material from memory. This method overwrites all bytes of the private key with zeros to prevent potential memory disclosure attacks. Should be called when the key is no longer needed.

type Ed25519phPublicKey

type Ed25519phPublicKey []byte

Ed25519phPublicKey represents an Ed25519 public key for Ed25519ph signature verification. The key format is identical to standard Ed25519 (32 bytes), but the verification algorithm uses pre-hashing with SHA-512 and domain separation per RFC 8032 §5.1.

CRITICAL: Always use NewEd25519phPublicKey() to create instances.

WRONG - Unsafe:

var key Ed25519phPublicKey  // Zero value - cryptographically invalid

CORRECT - Use constructor:

pubKey, err := ed25519ph.NewEd25519phPublicKey(pubBytes)
if err != nil {
    return err
}

func NewEd25519phPublicKey

func NewEd25519phPublicKey(data []byte) (Ed25519phPublicKey, error)

NewEd25519phPublicKey creates a validated Ed25519ph public key from bytes. This is the REQUIRED constructor - do not use var declarations or direct construction.

Parameters:

• data: Must be exactly 32 bytes

Returns error if data length is invalid.

func (Ed25519phPublicKey) Bytes

func (k Ed25519phPublicKey) Bytes() []byte

Bytes returns the raw byte representation of the Ed25519ph public key. The returned slice contains the 32-byte public key data suitable for serialization, transmission, or storage operations.

func (Ed25519phPublicKey) Len

func (k Ed25519phPublicKey) Len() int

Len returns the length of the Ed25519ph public key in bytes. Ed25519 public keys are always 32 bytes long as specified in RFC 8032.

func (Ed25519phPublicKey) NewVerifier

func (k Ed25519phPublicKey) NewVerifier() (v types.Verifier, err error)

NewVerifier creates a verifier instance that can validate Ed25519ph signatures. Returns a verifier configured with this public key for Ed25519ph signature verification. The verifier uses pre-hashing and domain separation per RFC 8032 §5.1.

type Ed25519phSigner

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

Ed25519phSigner provides digital signature creation using the Ed25519ph (pre-hashed) variant defined in RFC 8032 Section 5.1.

Unlike PureEdDSA, Ed25519ph first hashes the message with SHA-512, then signs the resulting digest with domain separation. This produces signatures that are distinct from and incompatible with standard Ed25519 signatures.

func (*Ed25519phSigner) Sign

func (s *Ed25519phSigner) Sign(data []byte) (sig []byte, err error)

Sign creates an Ed25519ph digital signature over the provided data. The data is first hashed with SHA-512, then signed using Ed25519ph with domain separation as specified in RFC 8032 Section 5.1. Returns the signature bytes or an error if signing fails.

func (*Ed25519phSigner) SignHash

func (s *Ed25519phSigner) SignHash(h []byte) (sig []byte, err error)

SignHash creates an Ed25519ph signature over a pre-computed SHA-512 hash. The hash must be exactly 64 bytes (SHA-512 output). The signature uses Ed25519ph domain separation per RFC 8032 Section 5.1, making it distinct from a PureEdDSA signature over the same hash bytes.

type Ed25519phVerifier

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

Ed25519phVerifier provides digital signature verification using the Ed25519ph (pre-hashed) variant defined in RFC 8032 §5.1.

This verifier expects signatures produced by Ed25519ph (with domain separation). It cannot verify standard Ed25519 (PureEdDSA) signatures.

func (*Ed25519phVerifier) Verify

func (v *Ed25519phVerifier) Verify(data, sig []byte) (err error)

Verify validates an Ed25519ph signature against arbitrary data. The data is first hashed with SHA-512, then verified using Ed25519ph with domain separation as specified in RFC 8032 §5.1. Returns an error if verification fails.

func (*Ed25519phVerifier) VerifyHash

func (v *Ed25519phVerifier) VerifyHash(h, sig []byte) (err error)

VerifyHash validates an Ed25519ph signature against a pre-computed SHA-512 hash. The hash must be exactly 64 bytes (SHA-512 output). Verification uses Ed25519ph domain separation per RFC 8032 §5.1. Returns an error if verification fails or inputs are invalid.