ed25519

Documentation

Overview

Package ed25519 provides a EdDSA (Edwards-curve Digital Signature Algorithm) handler for Curve25519.

The main component in the package is the 'KeyPair' instance. All functionality to generate and validate digital signatures is available by its methods.

Key Creation

There are 3 mechanisms to create a new key pair.

// 1. Create a completely random new key
rk, _ := New()

// 2. Key using a given seed material
sk, _ := FromSeed([]byte("material"))

// 3. Load from PEM-encoded content
pk, _ := Unmarshal(pemBinData)

However created, the key pair instance always use a locked memory buffer to securely hold private information. Is mandatory to properly release the memory buffer after using the key by calling the 'Destroy' method.

// Securely release in-memory secrets
kp.Destroy()

Key Usage

A key pair can be used to produce and verify digital signatures.

msg := []byte("message-to-sign")
kp, _ := New()
signature := kp.Sign(msg)
log.Printf("verification result: %v", kp.Verify(msg, signature))

Index

• func ToCurve25519(pub [32]byte) []byte
• func Verify(message, signature, publicKey []byte) bool
• type KeyPair
  • func FromPrivateKey(priv []byte) (*KeyPair, error)
  • func FromSeed(seed []byte) (*KeyPair, error)
  • func New() (*KeyPair, error)
  • func Unmarshal(src []byte) (*KeyPair, error)
  • func (k *KeyPair) DH(pub [32]byte) []byte
  • func (k *KeyPair) Destroy()
  • func (k *KeyPair) MarshalBinary() ([]byte, error)
  • func (k *KeyPair) PrivateKey() []byte
  • func (k *KeyPair) PublicKey() [32]byte
  • func (k *KeyPair) Sign(message []byte) []byte
  • func (k *KeyPair) ToX25519() [32]byte
  • func (k *KeyPair) UnmarshalBinary(data []byte) error
  • func (k *KeyPair) Verify(message, signature []byte) bool

Examples

• KeyPair.Verify
• Unmarshal

Functions

func ToCurve25519

func ToCurve25519(pub [32]byte) []byte

ToCurve25519 converts an Ed25519 public key to a Curve25519 public key.

func Verify

func Verify(message, signature, publicKey []byte) bool

Verify performs a digital signature verification.

Types

type KeyPair

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

KeyPair represents a Ed25519 (Sign/Verify) public/private key.

func FromPrivateKey

func FromPrivateKey(priv []byte) (*KeyPair, error)

FromPrivateKey restores a key pair instance using the provided private key value.

func FromSeed

func FromSeed(seed []byte) (*KeyPair, error)

FromSeed deterministically generates a keypair instance using the provided seed material. The KP instance needs to be securely removed from memory by calling the "Destroy" method.

func New

func New() (*KeyPair, error)

New randomly generated Ed25519 (Digital Signature) key pair. Each KP needs to be securely removed from memory by calling the "Destroy" method.

func Unmarshal

func Unmarshal(src []byte) (*KeyPair, error)

Unmarshal will restore a key pair instance from the provided PEM-encoded private key.

Example

// Restore key from a previously PEM-encoded private key
kp, err := Unmarshal([]byte("pem-encoded-private-key"))
if err != nil {
	panic(err)
}
defer kp.Destroy()

// Use the key to produce a signature
signature := kp.Sign([]byte("message-to-sign"))
fmt.Printf("signature produced: %x", signature)

func (*KeyPair) DH

func (k *KeyPair) DH(pub [32]byte) []byte

DH calculates a byte sequence which is the shared secret output from an Elliptic Curve Diffie-Hellman of the provided public key. In case of error the function return 'nil'.

func (*KeyPair) Destroy

func (k *KeyPair) Destroy()

Destroy will safely release the allocated mlock/VirtualLock memory.

func (*KeyPair) MarshalBinary

func (k *KeyPair) MarshalBinary() ([]byte, error)

MarshalBinary returns the PEM-encoded private key.

func (*KeyPair) PrivateKey

func (k *KeyPair) PrivateKey() []byte

PrivateKey returns the private key bytes of the key pair instance. Using this method may unintentionally expose secret material outside the security memory segment managed by the instance. Don't use it unless you really know what you are doing.

func (*KeyPair) PublicKey

func (k *KeyPair) PublicKey() [32]byte

PublicKey returns the public key bytes of the key pair instance.

func (*KeyPair) Sign

func (k *KeyPair) Sign(message []byte) []byte

Sign generates a digital signature for the provided content.

func (*KeyPair) ToX25519

func (k *KeyPair) ToX25519() [32]byte

ToX25519 returns a X25519 public key generated using the original keypair as seed material. The returned public key is suitable to perform secure Diffie-Hellman agreements using a single keypair instance.

func (*KeyPair) UnmarshalBinary

func (k *KeyPair) UnmarshalBinary(data []byte) error

UnmarshalBinary will restore a key pair instance from the provided PEM-encoded private key. The KP instance needs to be securely removed from memory by calling the "Destroy" method.

func (*KeyPair) Verify

func (k *KeyPair) Verify(message, signature []byte) bool

Verify performs a digital signature verification.

Example

msg := []byte("message-to-sign")
kp, _ := New()
signature := kp.Sign(msg)
fmt.Printf("verification result: %v", kp.Verify(msg, signature))