Add Support for Control Your Own Key (CYOK) and Bring Your Own Key (B…

…YOK) Features with New `EncryptionKeyManager` (#435)

go.mod

@@ -17,6 +17,7 @@ require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.3.0 // indirect
 	github.com/goccy/go-json v0.10.3 // indirect
+	github.com/google/go-cmp v0.6.0 // indirect
 	github.com/lestrrat-go/blackmagic v1.0.2 // indirect
 	github.com/lestrrat-go/httpcc v1.0.1 // indirect
 	github.com/lestrrat-go/httprc v1.0.6 // indirect

go.sum

@@ -12,8 +12,8 @@ github.com/decred/dcrd/dcrec/secp256k1/v4 v4.3.0/go.mod h1:v57UDF4pDQJcEfFUCRop3
 github.com/dustin/go-humanize v1.0.0/go.mod h1:HtrtbFcZ19U5GC7JDqmcUSB87Iq5E25KnS6fMYU6eOk=
 github.com/goccy/go-json v0.10.3 h1:KZ5WoDbxAIgm2HNbYckL0se1fHD6rz5j4ywS6ebzDqA=
 github.com/goccy/go-json v0.10.3/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
-github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
-github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=

management/encryption_key.go

@@ -0,0 +1,115 @@
+package management
+
+import (
+	"context"
+	"time"
+)
+
+// EncryptionKeyList is a list of encryption keys.
+type EncryptionKeyList struct {
+	List
+	Keys []*EncryptionKey `json:"keys"`
+}
+
+// EncryptionKey is used for encrypting data.
+type EncryptionKey struct {
+	// Key ID
+	KID *string `json:"kid,omitempty"`
+	// Key type
+	Type *string `json:"type,omitempty"`
+	// Key state
+	State *string `json:"state,omitempty"`
+	// Key creation timestamp
+	CreatedAt *time.Time `json:"created_at,omitempty"`
+	// Key update timestamp
+	UpdatedAt *time.Time `json:"updated_at,omitempty"`
+	// ID of parent wrapping key
+	ParentKID *string `json:"parent_kid,omitempty"`
+	// Base64 encoded ciphertext of key material wrapped by public wrapping key
+	WrappedKey *string `json:"wrapped_key,omitempty"`
+}
+
+// reset cleans up unnecessary fields based on the operation type.
+func (k *EncryptionKey) reset(op string) {
+	k.KID = nil
+	k.CreatedAt = nil
+	k.UpdatedAt = nil
+	k.ParentKID = nil
+	k.State = nil
+
+	switch op {
+	case "import":
+		k.Type = nil
+	case "create":
+		k.WrappedKey = nil
+	default:
+		k.Type = nil
+		k.WrappedKey = nil
+	}
+}
+
+// WrappingKey is used for creating the public wrapping key.
+type WrappingKey struct {
+	// The public key of the wrapping key for uploading the customer provided root key.
+	PublicKey *string `json:"public_key,omitempty"`
+	// The algorithm to be used for wrapping the key. Normally CKM_RSA_AES_KEY_WRAP
+	Algorithm *string `json:"algorithm,omitempty"`
+}
+
+// EncryptionKeyManager manages Auth0 EncryptionKey resources.
+type EncryptionKeyManager manager
+
+// Create an encryption key.
+//
+// See: https://auth0.com/docs/api/management/v2/keys/post-encryption
+func (m *EncryptionKeyManager) Create(ctx context.Context, e *EncryptionKey, opts ...RequestOption) error {
+	e.reset("create")
+	return m.management.Request(ctx, "POST", m.management.URI("keys", "encryption"), e, opts...)
+}
+
+// List all encryption keys.
+//
+// See: https://auth0.com/docs/api/management/v2/keys/get-encryption-keys
+func (m *EncryptionKeyManager) List(ctx context.Context, opts ...RequestOption) (ekl *EncryptionKeyList, err error) {
+	err = m.management.Request(ctx, "GET", m.management.URI("keys", "encryption"), &ekl, applyListDefaults(opts))
+	return
+}
+
+// Read an encryption key by its key id.
+//
+// See: https://auth0.com/docs/api/management/v2/keys/get-encryption-key
+func (m *EncryptionKeyManager) Read(ctx context.Context, kid string, opts ...RequestOption) (k *EncryptionKey, err error) {
+	err = m.management.Request(ctx, "GET", m.management.URI("keys", "encryption", kid), &k, opts...)
+	return
+}
+
+// Rekey the key hierarchy, Performs rekeying operation on the key hierarchy.
+//
+// See: https://auth0.com/docs/api/management/v2/keys/post-encryption-rekey
+func (m *EncryptionKeyManager) Rekey(ctx context.Context, opts ...RequestOption) error {
+	return m.management.Request(ctx, "POST", m.management.URI("keys", "encryption", "rekey"), nil, opts...)
+}
+
+// Delete an encryption key by its key id.
+//
+// See: https://auth0.com/docs/api/management/v2/keys/delete-encryption-key
+func (m *EncryptionKeyManager) Delete(ctx context.Context, kid string, opts ...RequestOption) error {
+	return m.management.Request(ctx, "DELETE", m.management.URI("keys", "encryption", kid), nil, opts...)
+}
+
+// ImportWrappedKey Imports wrapped key material and activate encryption key
+//
+// See: https://auth0.com/docs/api/management/v2/keys/post-encryption-key
+func (m *EncryptionKeyManager) ImportWrappedKey(ctx context.Context, e *EncryptionKey, opts ...RequestOption) error {
+	id := *e.KID
+	e.reset("import")
+	return m.management.Request(ctx, "POST", m.management.URI("keys", "encryption", id), e, opts...)
+}
+
+// CreatePublicWrappingKey creates the public wrapping key to wrap your own encryption key material.
+//
+// See: https://auth0.com/docs/api/management/v2/keys/post-encryption-wrapping-key
+func (m *EncryptionKeyManager) CreatePublicWrappingKey(ctx context.Context, kid string, opts ...RequestOption) (w *WrappingKey, err error) {
+	err = m.management.Request(ctx, "POST", m.management.URI("keys", "encryption", kid, "wrapping-key"), &w, opts...)
+	return
+}

management/encryption_key_test.go

@@ -0,0 +1,261 @@
+package management
+
+import (
+	"context"
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/sha256"
+	"crypto/x509"
+	"encoding/base64"
+	"encoding/binary"
+	"encoding/pem"
+	"fmt"
+	"math"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/auth0/go-auth0"
+)
+
+// Constants for wrapping sizes and parameters.
+const (
+	minWrapSize = 16
+	maxWrapSize = 8192
+	roundCount  = 6
+	ivPrefix    = uint32(0xA65959A6)
+)
+
+// kwpImpl is a Key Wrapping with Padding implementation.
+type kwpImpl struct {
+	block cipher.Block
+}
+
+func TestEncryptionKeyManager_Create(t *testing.T) {
+	configureHTTPTestRecordings(t)
+	givenEncryptionKey := &EncryptionKey{
+		Type: auth0.String("customer-provided-root-key"),
+	}
+	err := api.EncryptionKey.Create(context.Background(), givenEncryptionKey)
+	assert.NoError(t, err)
+	assert.NotEmpty(t, givenEncryptionKey.GetKID())
+	t.Cleanup(func() {
+		cleanUpEncryptionKey(t, givenEncryptionKey.GetKID())
+	})
+}
+
+func TestEncryptionKeyManager_List(t *testing.T) {
+	configureHTTPTestRecordings(t)
+	key := givenEncryptionKey(t)
+	keyList, err := api.EncryptionKey.List(context.Background(), PerPage(50), Page(0))
+	assert.NoError(t, err)
+	assert.Contains(t, keyList.Keys, key)
+}
+
+func TestEncryptionKeyManager_Read(t *testing.T) {
+	configureHTTPTestRecordings(t)
+	key := givenEncryptionKey(t)
+	readKey, err := api.EncryptionKey.Read(context.Background(), key.GetKID())
+	assert.NoError(t, err)
+	assert.Equal(t, key, readKey)
+}
+
+func TestEncryptionKeyManager_Rekey(t *testing.T) {
+	configureHTTPTestRecordings(t)
+	oldKeyList, err := api.EncryptionKey.List(context.Background(), PerPage(50), Page(0))
+	assert.NoError(t, err)
+	assert.NotEmpty(t, oldKeyList.Keys)
+
+	var oldKey, newKey *EncryptionKey
+	for _, key := range oldKeyList.Keys {
+		if key.GetState() == "active" && key.GetType() == "tenant-master-key" {
+			oldKey = key
+			break
+		}
+	}
+	assert.NotNil(t, oldKey)
+
+	err = api.EncryptionKey.Rekey(context.Background())
+	assert.NoError(t, err)
+
+	keyList, err := api.EncryptionKey.List(context.Background(), PerPage(50), Page(0))
+	assert.NoError(t, err)
+	assert.NotEmpty(t, keyList.Keys)
+
+	for _, key := range keyList.Keys {
+		if key.GetState() == "active" && key.GetType() == "tenant-master-key" {
+			newKey = key
+			break
+		}
+	}
+	assert.NotNil(t, newKey)
+
+	assert.NotEqual(t, oldKey.GetKID(), newKey.GetKID())
+	assert.NotEqual(t, keyList.Keys, oldKeyList.Keys)
+}
+
+func TestEncryptionKeyManager_Delete(t *testing.T) {
+	configureHTTPTestRecordings(t)
+	key := givenEncryptionKey(t)
+	err := api.EncryptionKey.Delete(context.Background(), key.GetKID())
+	assert.NoError(t, err)
+	keyRead, err := api.EncryptionKey.Read(context.Background(), key.GetKID())
+	assert.NoError(t, err)
+	assert.Equal(t, keyRead.GetState(), "destroyed")
+}
+
+func TestEncryptionKeyManager_CreatePublicWrappingKey(t *testing.T) {
+	configureHTTPTestRecordings(t)
+	key := givenEncryptionKey(t)
+	wrappingKey, err := api.EncryptionKey.CreatePublicWrappingKey(context.Background(), key.GetKID())
+	assert.NoError(t, err)
+	assert.NotEmpty(t, wrappingKey.GetPublicKey())
+}
+
+func TestEncryptionKeyManager_ImportWrappedKey(t *testing.T) {
+	configureHTTPTestRecordings(t)
+	key := givenEncryptionKey(t)
+	wrappingKey, err := api.EncryptionKey.CreatePublicWrappingKey(context.Background(), key.GetKID())
+	assert.NoError(t, err)
+	assert.NotEmpty(t, wrappingKey.GetPublicKey())
+
+	wrappedKeyStr, err := createAWSWrappedCiphertext(wrappingKey.GetPublicKey())
+	assert.NoError(t, err)
+
+	key.WrappedKey = &wrappedKeyStr
+	err = api.EncryptionKey.ImportWrappedKey(context.Background(), key)
+	assert.NoError(t, err)
+	assert.Equal(t, key.GetType(), "customer-provided-root-key")
+	assert.Equal(t, key.GetState(), "active")
+}
+
+func givenEncryptionKey(t *testing.T) *EncryptionKey {
+	t.Helper()
+	givenEncryptionKey := &EncryptionKey{
+		Type: auth0.String("customer-provided-root-key"),
+	}
+	err := api.EncryptionKey.Create(context.Background(), givenEncryptionKey)
+	assert.NoError(t, err)
+	assert.NotEmpty(t, givenEncryptionKey.GetKID())
+	t.Cleanup(func() {
+		cleanUpEncryptionKey(t, givenEncryptionKey.GetKID())
+	})
+	return givenEncryptionKey
+}
+
+func cleanUpEncryptionKey(t *testing.T, kid string) {
+	t.Helper()
+	err := api.EncryptionKey.Delete(context.Background(), kid)
+	assert.NoError(t, err)
+}
+
+func createAWSWrappedCiphertext(publicKeyPEM string) (string, error) {
+	block, _ := pem.Decode([]byte(publicKeyPEM))
+	if block == nil {
+		return "", fmt.Errorf("failed to decode public key PEM")
+	}
+
+	pubKey, err := x509.ParsePKIXPublicKey(block.Bytes)
+	if err != nil {
+		return "", fmt.Errorf("failed to parse public key: %w", err)
+	}
+
+	publicRSAKey, ok := pubKey.(*rsa.PublicKey)
+	if !ok {
+		return "", fmt.Errorf("public key is not of type *rsa.PublicKey")
+	}
+
+	ephemeralKey := make([]byte, 32)
+	if _, err := rand.Read(ephemeralKey); err != nil {
+		return "", fmt.Errorf("failed to generate ephemeral key: %w", err)
+	}
+
+	plaintextKey := make([]byte, 32)
+	if _, err := rand.Read(plaintextKey); err != nil {
+		return "", fmt.Errorf("failed to generate plaintext key: %w", err)
+	}
+
+	wrappedEphemeralKey, err := rsa.EncryptOAEP(sha256.New(), rand.Reader, publicRSAKey, ephemeralKey, nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to wrap ephemeral key: %w", err)
+	}
+
+	kwp, err := newKWP(ephemeralKey)
+	if err != nil {
+		return "", fmt.Errorf("failed to create KWP instance: %w", err)
+	}
+
+	wrappedTargetKey, err := kwp.wrap(plaintextKey)
+	if err != nil {
+		return "", fmt.Errorf("failed to wrap target key using KWP: %w", err)
+	}
+
+	wrappedEphemeralKey = append(wrappedEphemeralKey, wrappedTargetKey...)
+	return base64.StdEncoding.EncodeToString(wrappedEphemeralKey), nil
+}
+
+func newKWP(wrappingKey []byte) (*kwpImpl, error) {
+	switch len(wrappingKey) {
+	case 16, 32:
+		block, err := aes.NewCipher(wrappingKey)
+		if err != nil {
+			return nil, fmt.Errorf("kwp: error building AES cipher: %v", err)
+		}
+		return &kwpImpl{block: block}, nil
+	default:
+		return nil, fmt.Errorf("kwp: invalid AES key size; want 16 or 32, got %d", len(wrappingKey))
+	}
+}
+
+func wrappingSize(inputSize int) int {
+	paddingSize := 7 - (inputSize+7)%8
+	return inputSize + paddingSize + 8
+}
+
+func (kwp *kwpImpl) computeW(iv, key []byte) ([]byte, error) {
+	if len(key) <= 8 || len(key) > math.MaxInt32-16 || len(iv) != 8 {
+		return nil, fmt.Errorf("kwp: computeW called with invalid parameters")
+	}
+
+	data := make([]byte, wrappingSize(len(key)))
+	copy(data, iv)
+	copy(data[8:], key)
+	blockCount := len(data)/8 - 1
+
+	buf := make([]byte, 16)
+	copy(buf, data[:8])
+
+	for i := 0; i < roundCount; i++ {
+		for j := 0; j < blockCount; j++ {
+			copy(buf[8:], data[8*(j+1):])
+			kwp.block.Encrypt(buf, buf)
+
+			roundConst := uint(i*blockCount + j + 1)
+			for b := 0; b < 4; b++ {
+				buf[7-b] ^= byte(roundConst & 0xFF)
+				roundConst >>= 8
+			}
+
+			copy(data[8*(j+1):], buf[8:])
+		}
+	}
+	copy(data[:8], buf)
+	return data, nil
+}
+
+func (kwp *kwpImpl) wrap(data []byte) ([]byte, error) {
+	if len(data) < minWrapSize {
+		return nil, fmt.Errorf("kwp: key size to wrap too small")
+	}
+	if len(data) > maxWrapSize {
+		return nil, fmt.Errorf("kwp: key size to wrap too large")
+	}
+
+	iv := make([]byte, 8)
+	binary.BigEndian.PutUint32(iv, ivPrefix)
+	binary.BigEndian.PutUint32(iv[4:], uint32(len(data)))
+
+	return kwp.computeW(iv, data)
+}