add a crypto base layer that abstract various keypair type, + test/bench suite

Author: MichaelMure

crypto/ed25519/key.go

@@ -0,0 +1,30 @@
+package ed25519
+
+import (
+	"crypto/ed25519"
+	"crypto/rand"
+)
+
+const (
+	// PublicKeySize is the size, in bytes, of public keys as used in this package.
+	PublicKeySize = ed25519.PublicKeySize
+	// PrivateKeySize is the size, in bytes, of private keys as used in this package.
+	PrivateKeySize = ed25519.PrivateKeySize
+	// SignatureSize is the size, in bytes, of signatures generated and verified by this package.
+	SignatureSize = ed25519.SignatureSize
+
+	MultibaseCode = uint64(0xed)
+)
+
+func GenerateKeyPair() (PublicKey, PrivateKey, error) {
+	pub, priv, err := ed25519.GenerateKey(rand.Reader)
+	if err != nil {
+		return PublicKey{}, PrivateKey{}, err
+	}
+	return PublicKey{k: pub}, PrivateKey{k: priv}, nil
+}
+
+const (
+	pemPubBlockType  = "PUBLIC KEY"
+	pemPrivBlockType = "PRIVATE KEY"
+)

crypto/ed25519/key_test.go

@@ -0,0 +1,31 @@
+package ed25519
+
+import (
+	"testing"
+
+	"github.com/INFURA/go-did/crypto/internal"
+)
+
+var harness = helpers.TestHarness[PublicKey, PrivateKey]{
+	Name:                            "ed25519",
+	GenerateKeyPair:                 GenerateKeyPair,
+	PublicKeyFromBytes:              PublicKeyFromBytes,
+	PublicKeyFromPublicKeyMultibase: PublicKeyFromPublicKeyMultibase,
+	PublicKeyFromX509DER:            PublicKeyFromX509DER,
+	PublicKeyFromX509PEM:            PublicKeyFromX509PEM,
+	PrivateKeyFromBytes:             PrivateKeyFromBytes,
+	PrivateKeyFromPKCS8DER:          PrivateKeyFromPKCS8DER,
+	PrivateKeyFromPKCS8PEM:          PrivateKeyFromPKCS8PEM,
+	MultibaseCode:                   MultibaseCode,
+	PublicKeySize:                   PublicKeySize,
+	PrivateKeySize:                  PrivateKeySize,
+	SignatureSize:                   SignatureSize,
+}
+
+func TestSuite(t *testing.T) {
+	helpers.TestSuite(t, harness)
+}
+
+func BenchmarkSuite(b *testing.B) {
+	helpers.BenchSuite(b, harness)
+}

crypto/ed25519/private.go

@@ -0,0 +1,90 @@
+package ed25519
+
+import (
+	"crypto/ed25519"
+	"crypto/x509"
+	"encoding/pem"
+	"fmt"
+
+	"github.com/INFURA/go-did/crypto"
+)
+
+var _ crypto.SigningPrivateKey = &PrivateKey{}
+
+type PrivateKey struct {
+	k ed25519.PrivateKey
+}
+
+// PrivateKeyFromBytes converts a serialized private key to a PrivateKey.
+// This compact serialization format is the raw key material, without metadata or structure.
+// It errors if the slice is not the right size.
+func PrivateKeyFromBytes(b []byte) (PrivateKey, error) {
+	if len(b) != PrivateKeySize {
+		return PrivateKey{}, fmt.Errorf("invalid ed25519 private key size")
+	}
+	// make a copy
+	return PrivateKey{k: append([]byte{}, b...)}, nil
+}
+
+// PrivateKeyFromPKCS8DER decodes a PKCS#8 DER (binary) encoded private key.
+func PrivateKeyFromPKCS8DER(bytes []byte) (PrivateKey, error) {
+	priv, err := x509.ParsePKCS8PrivateKey(bytes)
+	if err != nil {
+		return PrivateKey{}, err
+	}
+	return PrivateKey{k: priv.(ed25519.PrivateKey)}, nil
+}
+
+// PrivateKeyFromPKCS8PEM decodes an PKCS#8 PEM (string) encoded private key.
+func PrivateKeyFromPKCS8PEM(str string) (PrivateKey, error) {
+	block, _ := pem.Decode([]byte(str))
+	if block == nil {
+		return PrivateKey{}, fmt.Errorf("failed to decode PEM block")
+	}
+	if block.Type != pemPrivBlockType {
+		return PrivateKey{}, fmt.Errorf("incorrect PEM block type")
+	}
+	return PrivateKeyFromPKCS8DER(block.Bytes)
+}
+
+func (p PrivateKey) Equal(other crypto.PrivateKey) bool {
+	if other, ok := other.(PrivateKey); ok {
+		return p.k.Equal(other.k)
+	}
+	return false
+}
+
+func (p PrivateKey) Public() crypto.PublicKey {
+	return PublicKey{k: p.k.Public().(ed25519.PublicKey)}
+}
+
+func (p PrivateKey) Sign(message []byte) ([]byte, error) {
+	return ed25519.Sign(p.k, message), nil
+}
+
+func (p PrivateKey) ToBytes() []byte {
+	// Copy the private key to a fixed size buffer that can get allocated on the
+	// caller's stack after inlining.
+	var buf [PrivateKeySize]byte
+	return append(buf[:0], p.k...)
+}
+
+func (p PrivateKey) ToPKCS8DER() []byte {
+	res, _ := x509.MarshalPKCS8PrivateKey(p.k)
+	return res
+}
+
+func (p PrivateKey) ToPKCS8PEM() string {
+	der := p.ToPKCS8DER()
+	return string(pem.EncodeToMemory(&pem.Block{
+		Type:  pemPrivBlockType,
+		Bytes: der,
+	}))
+}
+
+// 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 (p PrivateKey) Seed() []byte {
+	return p.k.Seed()
+}

crypto/ed25519/public.go

@@ -0,0 +1,99 @@
+package ed25519
+
+import (
+	"crypto/ed25519"
+	"crypto/x509"
+	"encoding/pem"
+	"fmt"
+
+	"github.com/INFURA/go-did/crypto"
+	"github.com/INFURA/go-did/crypto/internal"
+)
+
+var _ crypto.SigningPublicKey = &PublicKey{}
+
+type PublicKey struct {
+	k ed25519.PublicKey
+}
+
+// PublicKeyFromBytes converts a serialized public key to a PublicKey.
+// This compact serialization format is the raw key material, without metadata or structure.
+// It errors if the slice is not the right size.
+func PublicKeyFromBytes(b []byte) (PublicKey, error) {
+	if len(b) != PublicKeySize {
+		return PublicKey{}, fmt.Errorf("invalid ed25519 public key size")
+	}
+	// make a copy
+	return PublicKey{k: append([]byte{}, b...)}, nil
+}
+
+// PublicKeyFromPublicKeyMultibase decodes the public key from its PublicKeyMultibase form
+func PublicKeyFromPublicKeyMultibase(multibase string) (PublicKey, error) {
+	code, bytes, err := helpers.PublicKeyMultibaseDecode(multibase)
+	if err != nil {
+		return PublicKey{}, err
+	}
+	if code != MultibaseCode {
+		return PublicKey{}, fmt.Errorf("invalid code")
+	}
+	if len(bytes) != PublicKeySize {
+		return PublicKey{}, fmt.Errorf("invalid ed25519 public key size")
+	}
+	return PublicKeyFromBytes(bytes)
+}
+
+// PublicKeyFromX509DER decodes an X.509 DER (binary) encoded public key.
+func PublicKeyFromX509DER(bytes []byte) (PublicKey, error) {
+	pub, err := x509.ParsePKIXPublicKey(bytes)
+	if err != nil {
+		return PublicKey{}, err
+	}
+	return PublicKey{k: pub.(ed25519.PublicKey)}, nil
+}
+
+// PublicKeyFromX509PEM decodes an X.509 PEM (string) encoded public key.
+func PublicKeyFromX509PEM(str string) (PublicKey, error) {
+	block, _ := pem.Decode([]byte(str))
+	if block == nil {
+		return PublicKey{}, fmt.Errorf("failed to decode PEM block")
+	}
+	if block.Type != pemPubBlockType {
+		return PublicKey{}, fmt.Errorf("incorrect PEM block type")
+	}
+	return PublicKeyFromX509DER(block.Bytes)
+}
+
+func (p PublicKey) ToBytes() []byte {
+	// Copy the private key to a fixed size buffer that can get allocated on the
+	// caller's stack after inlining.
+	var buf [PublicKeySize]byte
+	return append(buf[:0], p.k...)
+}
+
+func (p PublicKey) ToPublicKeyMultibase() string {
+	return helpers.PublicKeyMultibaseEncode(MultibaseCode, p.k)
+}
+
+func (p PublicKey) ToX509DER() []byte {
+	res, _ := x509.MarshalPKIXPublicKey(p.k)
+	return res
+}
+
+func (p PublicKey) ToX509PEM() string {
+	der := p.ToX509DER()
+	return string(pem.EncodeToMemory(&pem.Block{
+		Type:  pemPubBlockType,
+		Bytes: der,
+	}))
+}
+
+func (p PublicKey) Equal(other crypto.PublicKey) bool {
+	if other, ok := other.(PublicKey); ok {
+		return p.k.Equal(other.k)
+	}
+	return false
+}
+
+func (p PublicKey) Verify(message, signature []byte) bool {
+	return ed25519.Verify(p.k, message, signature)
+}

crypto/interface.go

@@ -0,0 +1,41 @@
+package crypto
+
+type PublicKey interface {
+	Equal(other PublicKey) bool
+
+	ToBytes() []byte
+	ToPublicKeyMultibase() string
+	ToX509DER() []byte
+	ToX509PEM() string
+}
+
+type PrivateKey interface {
+	Equal(other PrivateKey) bool
+	Public() PublicKey
+
+	ToBytes() []byte
+	ToPKCS8DER() []byte
+	ToPKCS8PEM() string
+}
+
+type SigningPublicKey interface {
+	PublicKey
+
+	Verify(message, signature []byte) bool
+}
+
+type SigningPrivateKey interface {
+	PrivateKey
+
+	Sign(message []byte) ([]byte, error)
+}
+
+type KeyExchangePublicKey interface {
+	PublicKey
+
+	// PrivateKeyIsCompatible checks that the given PrivateKey is compatible to perform key exchange.
+	PrivateKeyIsCompatible(local PrivateKey) bool
+
+	// ECDH computes the shared key using the given PrivateKey.
+	ECDH(local PrivateKey) ([]byte, error)
+}

crypto/internal/multibase.go

@@ -0,0 +1,35 @@
+package helpers
+
+import (
+	"fmt"
+
+	mbase "github.com/multiformats/go-multibase"
+	"github.com/multiformats/go-varint"
+)
+
+// PublicKeyMultibaseDecode is a helper for decoding multibase public keys.
+func PublicKeyMultibaseDecode(multibase string) (uint64, []byte, error) {
+	baseCodec, bytes, err := mbase.Decode(multibase)
+	if err != nil {
+		return 0, nil, err
+	}
+	// the specification enforces that encoding
+	if baseCodec != mbase.Base58BTC {
+		return 0, nil, fmt.Errorf("not Base58BTC encoded")
+	}
+	code, read, err := varint.FromUvarint(bytes)
+	if err != nil {
+		return 0, nil, err
+	}
+	if read != 2 {
+		return 0, nil, fmt.Errorf("unexpected multibase")
+	}
+	return code, bytes[read:], nil
+}
+
+// PublicKeyMultibaseEncode is a helper for encoding multibase public keys.
+func PublicKeyMultibaseEncode(code uint64, bytes []byte) string {
+	// can only fail with an invalid encoding, but it's hardcoded
+	res, _ := mbase.Encode(mbase.Base58BTC, append(varint.ToUvarint(code), bytes...))
+	return res
+}