Add comments

pkg/services/encryption/encryption.go

@@ -2,6 +2,8 @@ package encryption
 
 import "context"
 
+// Service must not be used for encryption,
+// use secrets.Service implementing envelope encryption instead.
 type Service interface {
 	Encrypt(ctx context.Context, payload []byte, secret string) ([]byte, error)
 	Decrypt(ctx context.Context, payload []byte, secret string) ([]byte, error)

pkg/services/encryption/ossencryption/ossencryption.go

@@ -14,6 +14,8 @@ import (
 	"golang.org/x/crypto/pbkdf2"
 )
 
+// Service must not be used for encryption,
+// use secrets.Service implementing envelope encryption instead.
 type Service struct{}
 
 func ProvideService() *Service {

pkg/services/secrets/secrets.go

@@ -6,6 +6,8 @@ import (
 	"xorm.io/xorm"
 )
 
+// Service is an envelope encryption service in charge of encrypting/decrypting secrets.
+// It is a replacement for encryption.Service
 type Service interface {
 	Encrypt(ctx context.Context, payload []byte, opt EncryptionOptions) ([]byte, error)
 	Decrypt(ctx context.Context, payload []byte) ([]byte, error)
@@ -14,6 +16,7 @@ type Service interface {
 	GetDecryptedValue(ctx context.Context, sjd map[string][]byte, key, fallback string) string
 }
 
+// Store defines methods to interact with secrets storage
 type Store interface {
 	GetDataKey(ctx context.Context, name string) (*DataKey, error)
 	GetAllDataKeys(ctx context.Context) ([]*DataKey, error)
@@ -22,6 +25,7 @@ type Store interface {
 	DeleteDataKey(ctx context.Context, name string) error
 }
 
+// Provider is a key encryption key provider for envelope encryption
 type Provider interface {
 	Encrypt(ctx context.Context, blob []byte) ([]byte, error)
 	Decrypt(ctx context.Context, blob []byte) ([]byte, error)

pkg/util/encryption.go

@@ -15,8 +15,8 @@ import (
 const saltLength = 8
 
 // Decrypt decrypts a payload with a given secret.
-// Deprecated. Do not use it.
-// Use encryption.Service instead.
+// DEPRECATED. Do not use it.
+// Use secrets.Service instead.
 func Decrypt(payload []byte, secret string) ([]byte, error) {
 	if len(payload) < saltLength {
 		return nil, fmt.Errorf("unable to compute salt")
@@ -49,8 +49,8 @@ func Decrypt(payload []byte, secret string) ([]byte, error) {
 }
 
 // Encrypt encrypts a payload with a given secret.
-// Deprecated. Do not use it.
-// Use encryption.Service instead.
+// DEPRECATED. Do not use it.
+// Use secrets.Service instead.
 func Encrypt(payload []byte, secret string) ([]byte, error) {
 	salt, err := GetRandomString(saltLength)
 	if err != nil {