add higher level data types, move RSA to subpackage

Signed-off-by: Ashley Davis <ashley.davis@cyberark.com>

Author: SgtCoDFish

internal/envelope/doc.go

@@ -1,12 +1,12 @@
-// Package envelope implements RSA envelope encryption, intended to be used to secure sensitive Secret data from a cluster
-// being being sent to an external system. This protects against threats such as TLS interception middleware.
+// Package envelope provides types and interfaces for envelope encryption.
 //
-// Envelope encryption uses a combination of asymmetric encryption and symmetric encryption; since asymmetric encryption is
-// slow and has size limits, we generate a random symmetric key for each encryption operation, use that to encrypt the data,
-// then encrypt the symmetric key with the provided RSA public key. The recipient can then use their RSA private key to
-// decrypt the symmetric key, then use that to decrypt the data.
+// Envelope encryption combines asymmetric and symmetric cryptography to
+// efficiently encrypt data. The EncryptedData type holds the result, and
+// the Encryptor interface defines the encryption operation.
 //
-// This implementation uses RSA-OAEP with SHA-256 for asymmetric encryption, and AES-256-GCM for symmetric encryption.
+// Implementations are available in subpackages:
 //
-// In some documentation, the asymmetric key is called the "key encryption key" (KEK) and the symmetric key is called the "data encryption key" (DEK).
+//   - internal/envelope/rsa: RSA-OAEP + AES-256-GCM
+//
+// See subpackage documentation for usage examples.
 package envelope

internal/envelope/rsa/doc.go

@@ -0,0 +1,3 @@
+// Package rsa implements RSA envelope encryption, conforming to the interface in the envelope package.
+// It uses RSA-OAEP with SHA-256 for key encryption, and AES-256-GCM for data encryption.
+package rsa

internal/envelope/encryptor.go internal/envelope/rsa/encryptor.gointernal/envelope/encryptor.go renamed to internal/envelope/rsa/encryptor.go

@@ -1,4 +1,4 @@
-package envelope
+package rsa
 
 import (
 	"crypto/aes"
@@ -7,6 +7,8 @@ import (
 	"crypto/rsa"
 	"crypto/sha256"
 	"fmt"
+
+	"github.com/jetstack/preflight/internal/envelope"
 )
 
 const (
@@ -17,17 +19,24 @@ const (
 	// minRSAKeySize is the minimum RSA key size in bits; we'd expect that keys will be larger but 2048 is a sane floor
 	// to enforce to ensure that a weak key can't accidentally be used
 	minRSAKeySize = 2048
+
+	// keyAlgorithmIdentifier is set in EncryptedData to identify the key wrapping algorithm used in this package
+	keyAlgorithmIdentifier = "RSA-OAEP-SHA256"
 )
 
+// Compile-time check that Encryptor implements envelope.Encryptor
+var _ envelope.Encryptor = (*Encryptor)(nil)
+
 // Encryptor provides envelope encryption using RSA for key wrapping
 // and AES-256-GCM for data encryption.
 type Encryptor struct {
+	keyID        string
 	rsaPublicKey *rsa.PublicKey
 }
 
 // NewEncryptor creates a new Encryptor with the provided RSA public key.
 // The RSA key must be at least minRSAKeySize bits
-func NewEncryptor(publicKey *rsa.PublicKey) (*Encryptor, error) {
+func NewEncryptor(keyID string, publicKey *rsa.PublicKey) (*Encryptor, error) {
 	if publicKey == nil {
 		return nil, fmt.Errorf("RSA public key cannot be nil")
 	}
@@ -38,15 +47,20 @@ func NewEncryptor(publicKey *rsa.PublicKey) (*Encryptor, error) {
 		return nil, fmt.Errorf("RSA key size must be at least %d bits, got %d bits", minRSAKeySize, keySize)
 	}
 
+	if len(keyID) == 0 {
+		return nil, fmt.Errorf("keyID cannot be empty")
+	}
+
 	return &Encryptor{
+		keyID:        keyID,
 		rsaPublicKey: publicKey,
 	}, nil
 }
 
 // Encrypt performs envelope encryption on the provided data.
 // It generates a random AES-256 key, encrypts the data with AES-256-GCM,
 // then encrypts the AES key with RSA-OAEP-SHA256.
-func (e *Encryptor) Encrypt(data []byte) (*EncryptedData, error) {
+func (e *Encryptor) Encrypt(data []byte) (*envelope.EncryptedData, error) {
 	if len(data) == 0 {
 		return nil, fmt.Errorf("data to encrypt cannot be empty")
 	}
@@ -74,7 +88,9 @@ func (e *Encryptor) Encrypt(data []byte) (*EncryptedData, error) {
 		return nil, fmt.Errorf("failed to create GCM cipher: %w", err)
 	}
 
-	encryptedData := &EncryptedData{
+	encryptedData := &envelope.EncryptedData{
+		KeyID:         e.keyID,
+		KeyAlgorithm:  keyAlgorithmIdentifier,
 		EncryptedKey:  nil,
 		EncryptedData: nil,
 		Nonce:         make([]byte, gcm.NonceSize()),

internal/envelope/encryptor_test.go internal/envelope/rsa/encryptor_test.gointernal/envelope/encryptor_test.go renamed to internal/envelope/rsa/encryptor_test.go

@@ -1,15 +1,36 @@
-package envelope_test
+package rsa
 
 import (
 	"crypto/rand"
 	"crypto/rsa"
+	"sync"
 	"testing"
 
 	"github.com/stretchr/testify/require"
+)
+
+const testKeyID = "test-key-id"
 
-	"github.com/jetstack/preflight/internal/envelope"
+var (
+	testKeyOnce     sync.Once
+	internalTestKey *rsa.PrivateKey
 )
 
+// testKey generates and returns a singleton RSA private key for testing purposes,
+// to avoid needing to generate a new key for each test.
+func testKey() *rsa.PrivateKey {
+	testKeyOnce.Do(func() {
+		key, err := rsa.GenerateKey(rand.Reader, minRSAKeySize)
+		if err != nil {
+			panic("failed to generate test RSA key: " + err.Error())
+		}
+
+		internalTestKey = key
+	})
+
+	return internalTestKey
+}
+
 func TestNewEncryptor_ValidKeys(t *testing.T) {
 	tests := []struct {
 		name    string
@@ -25,7 +46,7 @@ func TestNewEncryptor_ValidKeys(t *testing.T) {
 			key, err := rsa.GenerateKey(rand.Reader, tt.keySize)
 			require.NoError(t, err)
 
-			enc, err := envelope.NewEncryptor(&key.PublicKey)
+			enc, err := NewEncryptor(testKeyID, &key.PublicKey)
 			require.NoError(t, err)
 			require.NotNil(t, enc)
 		})
@@ -36,24 +57,32 @@ func TestNewEncryptor_RejectsSmallKeys(t *testing.T) {
 	key, err := rsa.GenerateKey(rand.Reader, 1024)
 	require.NoError(t, err)
 
-	enc, err := envelope.NewEncryptor(&key.PublicKey)
+	enc, err := NewEncryptor(testKeyID, &key.PublicKey)
 	require.Error(t, err)
 	require.Nil(t, enc)
 	require.Contains(t, err.Error(), "must be at least 2048 bits")
 }
 
 func TestNewEncryptor_NilKey(t *testing.T) {
-	enc, err := envelope.NewEncryptor(nil)
+	enc, err := NewEncryptor(testKeyID, nil)
 	require.Error(t, err)
 	require.Nil(t, enc)
 	require.Contains(t, err.Error(), "cannot be nil")
 }
 
+func TestNewEncryptor_EmptyKeyID(t *testing.T) {
+	key := testKey()
+
+	enc, err := NewEncryptor("", &key.PublicKey)
+	require.Error(t, err)
+	require.Nil(t, enc)
+	require.Contains(t, err.Error(), "keyID cannot be empty")
+}
+
 func TestEncrypt_VariousDataSizes(t *testing.T) {
-	key, err := rsa.GenerateKey(rand.Reader, 2048)
-	require.NoError(t, err)
+	key := testKey()
 
-	enc, err := envelope.NewEncryptor(&key.PublicKey)
+	enc, err := NewEncryptor(testKeyID, &key.PublicKey)
 	require.NoError(t, err)
 
 	tests := []struct {
@@ -80,6 +109,10 @@ func TestEncrypt_VariousDataSizes(t *testing.T) {
 			require.NotEmpty(t, result.EncryptedData)
 			require.NotEmpty(t, result.Nonce)
 
+			// Verify KeyID and KeyAlgorithm are set correctly
+			require.Equal(t, testKeyID, result.KeyID)
+			require.Equal(t, keyAlgorithmIdentifier, result.KeyAlgorithm)
+
 			// Verify nonce is correct size (12 bytes for GCM)
 			require.Len(t, result.Nonce, 12)
 
@@ -90,10 +123,9 @@ func TestEncrypt_VariousDataSizes(t *testing.T) {
 }
 
 func TestEncrypt_EmptyData(t *testing.T) {
-	key, err := rsa.GenerateKey(rand.Reader, 2048)
-	require.NoError(t, err)
+	key := testKey()
 
-	enc, err := envelope.NewEncryptor(&key.PublicKey)
+	enc, err := NewEncryptor(testKeyID, &key.PublicKey)
 	require.NoError(t, err)
 
 	result, err := enc.Encrypt([]byte{})
@@ -103,10 +135,9 @@ func TestEncrypt_EmptyData(t *testing.T) {
 }
 
 func TestEncrypt_NonDeterministic(t *testing.T) {
-	key, err := rsa.GenerateKey(rand.Reader, 2048)
-	require.NoError(t, err)
+	key := testKey()
 
-	enc, err := envelope.NewEncryptor(&key.PublicKey)
+	enc, err := NewEncryptor(testKeyID, &key.PublicKey)
 	require.NoError(t, err)
 
 	data := []byte("test data for encryption")
@@ -118,6 +149,12 @@ func TestEncrypt_NonDeterministic(t *testing.T) {
 	result2, err := enc.Encrypt(data)
 	require.NoError(t, err)
 
+	// Verify KeyID and KeyAlgorithm are set correctly in both results
+	require.Equal(t, testKeyID, result1.KeyID)
+	require.Equal(t, keyAlgorithmIdentifier, result1.KeyAlgorithm)
+	require.Equal(t, testKeyID, result2.KeyID)
+	require.Equal(t, keyAlgorithmIdentifier, result2.KeyAlgorithm)
+
 	// Nonces should be different (random)
 	require.NotEqual(t, result1.Nonce, result2.Nonce)
 
@@ -129,10 +166,9 @@ func TestEncrypt_NonDeterministic(t *testing.T) {
 }
 
 func TestEncrypt_AllFieldsPopulated(t *testing.T) {
-	key, err := rsa.GenerateKey(rand.Reader, 2048)
-	require.NoError(t, err)
+	key := testKey()
 
-	enc, err := envelope.NewEncryptor(&key.PublicKey)
+	enc, err := NewEncryptor(testKeyID, &key.PublicKey)
 	require.NoError(t, err)
 
 	data := []byte("test data")
@@ -144,6 +180,10 @@ func TestEncrypt_AllFieldsPopulated(t *testing.T) {
 	require.NotEmpty(t, result.EncryptedData, "EncryptedData should be populated")
 	require.NotEmpty(t, result.Nonce, "Nonce should be populated")
 
+	// Verify KeyID and KeyAlgorithm are set correctly
+	require.Equal(t, testKeyID, result.KeyID, "KeyID should match the encryptor's keyID")
+	require.Equal(t, keyAlgorithmIdentifier, result.KeyAlgorithm, "KeyAlgorithm should be the value of keyAlgorithmIdentifier")
+
 	// Verify encrypted key size is appropriate for RSA 2048
 	require.Equal(t, 256, len(result.EncryptedKey), "EncryptedKey should be 256 bytes for RSA 2048")
 }

internal/envelope/keys.go internal/envelope/rsa/keys.gointernal/envelope/keys.go renamed to internal/envelope/rsa/keys.go

@@ -1,4 +1,4 @@
-package envelope
+package rsa
 
 import (
 	"crypto/rsa"

internal/envelope/keys_test.go internal/envelope/rsa/keys_test.gointernal/envelope/keys_test.go renamed to internal/envelope/rsa/keys_test.go

@@ -1,4 +1,4 @@
-package envelope_test
+package rsa_test
 
 import (
 	"crypto/ecdsa"
@@ -13,7 +13,7 @@ import (
 
 	"github.com/stretchr/testify/require"
 
-	"github.com/jetstack/preflight/internal/envelope"
+	internalrsa "github.com/jetstack/preflight/internal/envelope/rsa"
 )
 
 func generateTestKeyPEM(t *testing.T, keySize int, pemType string) []byte {
@@ -49,7 +49,7 @@ func generateTestKeyPEM(t *testing.T, keySize int, pemType string) []byte {
 func TestLoadPublicKeyFromPEM_PKIX(t *testing.T) {
 	pemBytes := generateTestKeyPEM(t, 2048, "PUBLIC KEY")
 
-	key, err := envelope.LoadPublicKeyFromPEM(pemBytes)
+	key, err := internalrsa.LoadPublicKeyFromPEM(pemBytes)
 	require.NoError(t, err)
 	require.NotNil(t, key)
 	require.Equal(t, 2048, key.N.BitLen())
@@ -58,7 +58,7 @@ func TestLoadPublicKeyFromPEM_PKIX(t *testing.T) {
 func TestLoadPublicKeyFromPEM_PKCS1(t *testing.T) {
 	pemBytes := generateTestKeyPEM(t, 2048, "RSA PUBLIC KEY")
 
-	key, err := envelope.LoadPublicKeyFromPEM(pemBytes)
+	key, err := internalrsa.LoadPublicKeyFromPEM(pemBytes)
 	require.NoError(t, err)
 	require.NotNil(t, key)
 	require.Equal(t, 2048, key.N.BitLen())
@@ -67,7 +67,7 @@ func TestLoadPublicKeyFromPEM_PKCS1(t *testing.T) {
 func TestLoadPublicKeyFromPEM_InvalidPEM(t *testing.T) {
 	invalidPEM := []byte("this is not a valid PEM")
 
-	key, err := envelope.LoadPublicKeyFromPEM(invalidPEM)
+	key, err := internalrsa.LoadPublicKeyFromPEM(invalidPEM)
 	require.Error(t, err)
 	require.Nil(t, key)
 	require.Contains(t, err.Error(), "failed to decode PEM block")
@@ -84,7 +84,7 @@ func TestLoadPublicKeyFromPEM_WrongPEMType(t *testing.T) {
 		Bytes: privateKeyBytes,
 	})
 
-	key, err := envelope.LoadPublicKeyFromPEM(pemBytes)
+	key, err := internalrsa.LoadPublicKeyFromPEM(pemBytes)
 	require.Error(t, err)
 	require.Nil(t, key)
 	require.Contains(t, err.Error(), "unsupported PEM block type")
@@ -104,7 +104,7 @@ func TestLoadPublicKeyFromPEM_NonRSAKey(t *testing.T) {
 		Bytes: publicKeyBytes,
 	})
 
-	key, err := envelope.LoadPublicKeyFromPEM(pemBytes)
+	key, err := internalrsa.LoadPublicKeyFromPEM(pemBytes)
 	require.Error(t, err)
 	require.Nil(t, key)
 	require.Contains(t, err.Error(), "not an RSA public key")
@@ -118,14 +118,14 @@ func TestLoadPublicKeyFromPEMFile_ValidFile(t *testing.T) {
 	err := os.WriteFile(keyPath, pemBytes, 0600)
 	require.NoError(t, err)
 
-	key, err := envelope.LoadPublicKeyFromPEMFile(keyPath)
+	key, err := internalrsa.LoadPublicKeyFromPEMFile(keyPath)
 	require.NoError(t, err)
 	require.NotNil(t, key)
 	require.Equal(t, 2048, key.N.BitLen())
 }
 
 func TestLoadPublicKeyFromPEMFile_MissingFile(t *testing.T) {
-	key, err := envelope.LoadPublicKeyFromPEMFile("/nonexistent/path/key.pem")
+	key, err := internalrsa.LoadPublicKeyFromPEMFile("/nonexistent/path/key.pem")
 	require.Error(t, err)
 	require.Nil(t, key)
 	require.Contains(t, err.Error(), "failed to read PEM file")
@@ -138,7 +138,7 @@ func TestLoadPublicKeyFromPEMFile_InvalidContent(t *testing.T) {
 	err := os.WriteFile(keyPath, []byte("not a valid PEM"), 0600)
 	require.NoError(t, err)
 
-	key, err := envelope.LoadPublicKeyFromPEMFile(keyPath)
+	key, err := internalrsa.LoadPublicKeyFromPEMFile(keyPath)
 	require.Error(t, err)
 	require.Nil(t, key)
 }

internal/envelope/types.go

@@ -1,18 +1,31 @@
 package envelope
 
 // EncryptedData contains the result of envelope encryption.
-// It includes the encrypted data, the encrypted AES key which was used for encrypting the original data,
-// and the nonce needed for AES-GCM decryption.
+// It includes the encrypted data, the encrypted symmetric key which was used for encrypting the original data,
+// and the nonce needed for the symmetric decryption.
 type EncryptedData struct {
-	// EncryptedKey is the AES-256 key encrypted with RSA-OAEP-SHA256.
-	// This is ciphertext and should only be decryptable by the holder of the corresponding RSA private key.
+	// KeyID is the identifier of the asymmetric key used to encrypt the AES key.
+	KeyID string `json:"key_id"`
+
+	// KeyAlgorithm is the algorithm of the asymmetric key used to encrypt the AES key.
+	KeyAlgorithm string `json:"key_algorithm"`
+
+	// EncryptedKey is an encrypted AES-256-GCM symmetric key, used to encrypt EncryptedData.
+	// This is ciphertext and should only be decryptable by the holder of the private key.
 	EncryptedKey []byte `json:"encrypted_key"`
 
-	// EncryptedData is the actual data encrypted using AES-256-GCM.
-	// This is ciphertext and requires the AES key (after RSA decryption) and nonce for decryption.
+	// EncryptedData is the actual data encrypted using the AES-256-GCM in EncryptedKey.
+	// This is ciphertext and requires the decrypted AES key and nonce for decryption.
 	EncryptedData []byte `json:"encrypted_data"`
 
 	// Nonce is the 12-byte nonce used for AES-GCM encryption.
 	// This is intentionally plaintext.
 	Nonce []byte `json:"nonce"`
 }
+
+// Encryptor performs envelope encryption on arbitrary data.
+type Encryptor interface {
+	// Encrypt encrypts data using envelope encryption, returning the resulting data along
+	// with identifiers of the asymmetric key used to encrypt the AES key.
+	Encrypt(data []byte) (*EncryptedData, error)
+}