Merge pull request #9 from INFURA/crypto

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 (
+	// PublicKeyBytesSize is the size, in bytes, of public keys in raw bytes.
+	PublicKeyBytesSize = ed25519.PublicKeySize
+	// PrivateKeyBytesSize is the size, in bytes, of private keys in raw bytes.
+	PrivateKeyBytesSize = ed25519.PrivateKeySize
+	// SignatureBytesSize is the size, in bytes, of signatures in raw bytes.
+	SignatureBytesSize = 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,
+	PublicKeyBytesSize:              PublicKeyBytesSize,
+	PrivateKeyBytesSize:             PrivateKeyBytesSize,
+	SignatureBytesSize:              SignatureBytesSize,
+}
+
+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,101 @@
+package ed25519
+
+import (
+	"crypto/ed25519"
+	"crypto/x509"
+	"encoding/pem"
+	"fmt"
+
+	"golang.org/x/crypto/cryptobyte"
+
+	"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) != PrivateKeyBytesSize {
+		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) SignToBytes(message []byte) ([]byte, error) {
+	return ed25519.Sign(p.k, message), nil
+}
+
+// SignToASN1 creates a signature with ASN.1 encoding.
+// This ASN.1 encoding uses a BIT STRING, which would be correct for an X.509 certificate.
+func (p PrivateKey) SignToASN1(message []byte) ([]byte, error) {
+	sig := ed25519.Sign(p.k, message)
+	var b cryptobyte.Builder
+	b.AddASN1BitString(sig)
+	return b.Bytes()
+}
+
+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 [PrivateKeyBytesSize]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,118 @@
+package ed25519
+
+import (
+	"crypto/ed25519"
+	"crypto/x509"
+	"encoding/asn1"
+	"encoding/pem"
+	"fmt"
+
+	"golang.org/x/crypto/cryptobyte"
+
+	"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) != PublicKeyBytesSize {
+		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) != PublicKeyBytesSize {
+		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 [PublicKeyBytesSize]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) VerifyBytes(message, signature []byte) bool {
+	return ed25519.Verify(p.k, message, signature)
+}
+
+// VerifyASN1 verifies a signature with ASN.1 encoding.
+// This ASN.1 encoding uses a BIT STRING, which would be correct for an X.509 certificate.
+func (p PublicKey) VerifyASN1(message, signature []byte) bool {
+	var s cryptobyte.String = signature
+	var bitString asn1.BitString
+
+	if !s.ReadASN1BitString(&bitString) {
+		return false
+	}
+	if bitString.BitLength != SignatureBytesSize*8 {
+		return false
+	}
+
+	return ed25519.Verify(p.k, message, bitString.Bytes)
+}

crypto/interface.go

@@ -0,0 +1,74 @@
+package crypto
+
+type PublicKey interface {
+	// Equal returns true if other is the same PublicKey
+	Equal(other PublicKey) bool
+
+	// ToBytes serializes the PublicKey into "raw bytes", without metadata or structure.
+	// This format can make some assumptions and may not be what you expect.
+	// Ideally, this format is defined by the same specification as the underlying crypto scheme.
+	ToBytes() []byte
+
+	// ToPublicKeyMultibase format the PublicKey into a string compatible with a PublicKeyMultibase field
+	// in a DID Document.
+	ToPublicKeyMultibase() string
+
+	// ToX509DER serializes the PublicKey into the X.509 DER (binary) format.
+	ToX509DER() []byte
+
+	// ToX509PEM serializes the PublicKey into the X.509 PEM (string) format.
+	ToX509PEM() string
+}
+
+type PrivateKey interface {
+	// Equal returns true if other is the same PrivateKey
+	Equal(other PrivateKey) bool
+
+	// Public returns the matching PublicKey.
+	Public() PublicKey
+
+	// ToBytes serializes the PrivateKey into "raw bytes", without metadata or structure.
+	// This format can make some assumptions and may not be what you expect.
+	// Ideally, this format is defined by the same specification as the underlying crypto scheme.
+	ToBytes() []byte
+
+	// ToPKCS8DER serializes the PrivateKey into the PKCS#8 DER (binary) format.
+	ToPKCS8DER() []byte
+
+	// ToPKCS8PEM serializes the PrivateKey into the PKCS#8 PEM (string) format.
+	ToPKCS8PEM() string
+}
+
+type SigningPublicKey interface {
+	PublicKey
+
+	// VerifyBytes checks a signature in the "raw bytes" format.
+	// This format can make some assumptions and may not be what you expect.
+	// Ideally, this format is defined by the same specification as the underlying crypto scheme.
+	VerifyBytes(message, signature []byte) bool
+
+	// VerifyASN1 checks a signature in the ASN.1 format.
+	VerifyASN1(message, signature []byte) bool
+}
+
+type SigningPrivateKey interface {
+	PrivateKey
+
+	// SignToBytes creates a signature in the "raw bytes" format.
+	// This format can make some assumptions and may not be what you expect.
+	// Ideally, this format is defined by the same specification as the underlying crypto scheme.
+	SignToBytes(message []byte) ([]byte, error)
+
+	// SignToASN1 creates a signature in the ASN.1 format.
+	SignToASN1(message []byte) ([]byte, error)
+}
+
+type KeyExchangePrivateKey interface {
+	PrivateKey
+
+	// PublicKeyIsCompatible checks that the given PublicKey is compatible to perform key exchange.
+	PublicKeyIsCompatible(remote PublicKey) bool
+
+	// KeyExchange computes the shared key using the given PublicKey.
+	KeyExchange(remote PublicKey) ([]byte, error)
+}

verifications/internal/multibase.go crypto/internal/multibase.goverifications/internal/multibase.go renamed to crypto/internal/multibase.go

@@ -7,8 +7,8 @@ import (
 	"github.com/multiformats/go-varint"
 )
 
-// MultibaseDecode is a helper for decoding multibase public keys.
-func MultibaseDecode(multibase string) (uint64, []byte, error) {
+// 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
@@ -27,8 +27,8 @@ func MultibaseDecode(multibase string) (uint64, []byte, error) {
 	return code, bytes[read:], nil
 }
 
-// MultibaseEncode is a helper for encoding multibase public keys.
-func MultibaseEncode(code uint64, bytes []byte) string {
+// 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