Documentation
¶
Overview ¶
Package sops provides SOPS encryption, decryption, and editing operations for YAML and JSON files. It wraps the core SOPS library to provide a simplified API for age-based key management and file operations.
Index ¶
- Constants
- Variables
- func AppendToExistingFile(targetPath, formattedKey string) error
- func CanonicalizeAndGetStores(inputPath string) (string, sops.Store, sops.Store, error)
- func CreateEditorCommand(path string) (*exec.Cmd, error)
- func CreateSOPSTree(branches sops.TreeBranches, config EncryptConfig, inputPath string) (*sops.Tree, error)
- func CreateTempDir() (string, func(), error)
- func CreateTempFileWithContent(opts EditOpts, tree *sops.Tree) (string, func(), error)
- func Decrypt(opts DecryptOpts) ([]byte, error)
- func DecryptTree(opts DecryptOpts) (*sops.Tree, error)
- func DecryptTreeWithKey(opts DecryptOpts) (*sops.Tree, []byte, error)
- func DerivePublicKey(privateKey string) (string, error)
- func Edit(opts EditOpts) ([]byte, error)
- func EditExample(opts EditExampleOpts) ([]byte, error)
- func EditNewFile(opts EditOpts, inputStore sops.Store) ([]byte, error)
- func EditTree(opts EditOpts, tree *sops.Tree, dataKey []byte) ([]byte, error)
- func EmitTreeContent(opts EditOpts, tree *sops.Tree) ([]byte, error)
- func Encrypt(opts EncryptOpts) ([]byte, error)
- func EncryptAndEmit(opts EditOpts, tree *sops.Tree, dataKey []byte) ([]byte, error)
- func EncryptTreeAndEmit(tree *sops.Tree, dataKey []byte, cipher sops.Cipher, outputStore sops.Store) ([]byte, error)
- func EnsureNoMetadata(opts EncryptOpts, branch sops.TreeBranch) error
- func Extract(tree *sops.Tree, path []any, outputStore sops.Store) ([]byte, error)
- func FormatAgeKeyWithMetadata(privateKey, publicKey string) string
- func GetAgeKeyPath() (string, error)
- func GetDecryptStores(inputPath string, readFromStdin bool) (sops.Store, sops.Store, error)
- func GetStores(inputPath string) (sops.Store, sops.Store, error)
- func HandleEmitError(err error, data []byte) ([]byte, error)
- func HandleMasterKeysMode(opts RunEditorUntilOkOpts, edited []byte) error
- func HandleNewFile(targetPath, formattedKey string, statErr error) error
- func HashFile(filePath string) ([]byte, error)
- func ImportKey(privateKey string) error
- func LoadFile(opts EncryptOpts) ([]byte, error)
- func LookupAnyEditor(editorNames ...string) (string, error)
- func MetadataFromEncryptionConfig(config EncryptConfig) sops.Metadata
- func ParseEditorCommand(editor, envVar string) ([]string, error)
- func ParseExtractPath(extract string) ([]any, error)
- func ProcessEditedContent(opts RunEditorUntilOkOpts, edited []byte) (bool, error)
- func RunEditor(path string) error
- func RunEditorUntilOk(opts RunEditorUntilOkOpts) error
- func ValidateAgeKey(privateKey string) error
- func ValidateEditedFile(opts RunEditorUntilOkOpts) (bool, error)
- func ValidateTreeMetadata(opts RunEditorUntilOkOpts) (bool, error)
- func WriteKeyToFile(targetPath, formattedKey string) error
- func WriteTempFile(tmpdir string, opts EditOpts, tree *sops.Tree, cleanup func()) (string, error)
- type DecryptOpts
- type EditExampleOpts
- type EditOpts
- type EncryptConfig
- type EncryptOpts
- type FileAlreadyEncryptedError
- type RunEditorUntilOkOpts
- type StoreWithExample
Constants ¶
const ( // TmpFilePermissions is the permission mode for temporary files during edit. TmpFilePermissions = os.FileMode(0o600) // EncryptedFilePermissions is the permission mode for encrypted output files. EncryptedFilePermissions = os.FileMode(0o644) // DecryptedFilePermissions is the permission mode for decrypted output files. DecryptedFilePermissions = os.FileMode(0o600) // AgeKeyFilePermissions is the permission mode for age key files. AgeKeyFilePermissions = os.FileMode(0o600) // AgeKeyDirPermissions is the permission mode for the age key directory. AgeKeyDirPermissions = os.FileMode(0o700) // AgeKeyPrefix is the expected prefix for age private keys. AgeKeyPrefix = "AGE-SECRET-KEY-" // MinAgeKeyLength is the minimum required length for age private keys. MinAgeKeyLength = 60 )
const NotBinaryHint = "This is likely not an encrypted binary file."
NotBinaryHint provides a user-friendly message when SOPS encounters binary data.
Variables ¶
var ( ErrDumpingTree = errors.New("error dumping file") ErrInvalidExtractPath = errors.New("invalid extract path format") ErrInvalidEditor = errors.New("invalid editor configuration") ErrNoEditorAvailable = errors.New("no editor available") ErrStoreNoExampleGeneration = errors.New("store does not support example file generation") ErrCouldNotGenerateDataKey = errors.New("could not generate data key") ErrUnsupportedFileFormat = errors.New("unsupported file format") ErrInvalidAgeKey = errors.New("invalid age key format") ErrFailedToCreateDir = errors.New("failed to create directory") ErrFailedToWriteKey = errors.New("failed to write key") ErrFailedToDetermineAge = errors.New("failed to determine age key path") )
Exported error variables for SOPS operations.
Functions ¶
func AppendToExistingFile ¶
AppendToExistingFile appends the formatted key to an existing file.
func CanonicalizeAndGetStores ¶
CanonicalizeAndGetStores resolves the input path to a canonical form and returns the appropriate SOPS stores.
func CreateEditorCommand ¶
CreateEditorCommand creates the exec.Cmd for the editor.
func CreateSOPSTree ¶
func CreateSOPSTree( branches sops.TreeBranches, config EncryptConfig, inputPath string, ) (*sops.Tree, error)
CreateSOPSTree creates a SOPS tree with the given branches, metadata config, and input path.
func CreateTempDir ¶
CreateTempDir creates a temporary directory for editing.
func CreateTempFileWithContent ¶
CreateTempFileWithContent creates a temporary file with the tree content.
func Decrypt ¶
func Decrypt(opts DecryptOpts) ([]byte, error)
Decrypt performs the core decryption logic for a file. It loads the encrypted file, decrypts it, and handles extraction if specified.
func DecryptTree ¶
func DecryptTree(opts DecryptOpts) (*sops.Tree, error)
DecryptTree loads and decrypts a SOPS tree from the input file. It handles loading the encrypted file and decrypting its contents.
func DecryptTreeWithKey ¶
func DecryptTreeWithKey(opts DecryptOpts) (*sops.Tree, []byte, error)
DecryptTreeWithKey loads and decrypts a SOPS tree, returning both tree and data key. This is useful when the caller needs the data key for re-encryption.
func DerivePublicKey ¶
DerivePublicKey derives the public key from an age private key.
func EditExample ¶
func EditExample(opts EditExampleOpts) ([]byte, error)
EditExample creates and edits an example file when the target file doesn't exist.
func EditNewFile ¶
EditNewFile handles editing a new file that doesn't exist yet.
func EditTree ¶
EditTree handles the core edit workflow: write to temp file, launch editor, re-encrypt.
func EmitTreeContent ¶
EmitTreeContent emits the tree content for editing.
func Encrypt ¶
func Encrypt(opts EncryptOpts) ([]byte, error)
Encrypt performs the core encryption logic for a file. It loads the file, validates that it's not already encrypted, generates encryption keys using the configured key services, encrypts the data, and returns the encrypted file content.
func EncryptAndEmit ¶
EncryptAndEmit encrypts the tree and emits the encrypted file.
func EncryptTreeAndEmit ¶
func EncryptTreeAndEmit( tree *sops.Tree, dataKey []byte, cipher sops.Cipher, outputStore sops.Store, ) ([]byte, error)
EncryptTreeAndEmit encrypts a tree and emits the encrypted file content. This is a common helper shared by encrypt and edit operations.
func EnsureNoMetadata ¶
func EnsureNoMetadata(opts EncryptOpts, branch sops.TreeBranch) error
EnsureNoMetadata checks whether a file already contains SOPS metadata. This prevents re-encryption of already encrypted files, which would corrupt them.
func Extract ¶
Extract retrieves a specific value or subtree from the decrypted tree. It supports extracting nested keys using a path array.
func FormatAgeKeyWithMetadata ¶
FormatAgeKeyWithMetadata formats an age private key with metadata comments.
func GetAgeKeyPath ¶
GetAgeKeyPath returns the platform-specific path for the age keys file. It follows the SOPS convention:
- First checks SOPS_AGE_KEY_FILE environment variable
- Linux: $XDG_CONFIG_HOME/sops/age/keys.txt or $HOME/.config/sops/age/keys.txt
- macOS: $XDG_CONFIG_HOME/sops/age/keys.txt or $HOME/Library/Application Support/sops/age/keys.txt
- Windows: %AppData%\sops\age\keys.txt
func GetDecryptStores ¶
GetDecryptStores returns the appropriate SOPS stores for decryption. When reading from stdin, it defaults to YAML format. For JSON format from stdin, users can pipe to a file first.
func GetStores ¶
GetStores returns the appropriate SOPS stores (input and output) based on file extension. It supports YAML (.yaml, .yml) and JSON (.json) file formats.
func HandleEmitError ¶
HandleEmitError processes errors from EmitPlainFile operations.
func HandleMasterKeysMode ¶
func HandleMasterKeysMode(opts RunEditorUntilOkOpts, edited []byte) error
HandleMasterKeysMode handles the show master keys mode validation.
func HandleNewFile ¶
HandleNewFile creates a new file with the formatted key or returns an error if stat failed for other reasons.
func LoadFile ¶
func LoadFile(opts EncryptOpts) ([]byte, error)
LoadFile reads file content either from stdin or from a file path. The source is determined by the ReadFromStdin option.
func LookupAnyEditor ¶
LookupAnyEditor searches for any of the specified editors in PATH.
func MetadataFromEncryptionConfig ¶
func MetadataFromEncryptionConfig(config EncryptConfig) sops.Metadata
MetadataFromEncryptionConfig creates SOPS metadata from the encryption configuration. It converts the EncryptConfig fields into a sops.Metadata structure that will be stored in the encrypted file.
func ParseEditorCommand ¶
ParseEditorCommand parses the editor command string.
func ParseExtractPath ¶
ParseExtractPath converts a JSONPath-like extract string into a path array. Example: '["data"]["password"]' -> []any{"data", "password"}.
func ProcessEditedContent ¶
func ProcessEditedContent(opts RunEditorUntilOkOpts, edited []byte) (bool, error)
ProcessEditedContent processes the edited content and updates the tree.
func RunEditor ¶
RunEditor launches the editor specified by SOPS_EDITOR or EDITOR environment variables. Falls back to vim, nano, or vi if no editor is configured.
func RunEditorUntilOk ¶
func RunEditorUntilOk(opts RunEditorUntilOkOpts) error
RunEditorUntilOk runs the editor in a loop until the file is valid or user cancels.
func ValidateAgeKey ¶
ValidateAgeKey performs basic validation on an age private key string. The input must start with "AGE-SECRET-KEY-" and meet minimum length requirements.
func ValidateEditedFile ¶
func ValidateEditedFile(opts RunEditorUntilOkOpts) (bool, error)
ValidateEditedFile validates the edited file and updates the tree.
func ValidateTreeMetadata ¶
func ValidateTreeMetadata(opts RunEditorUntilOkOpts) (bool, error)
ValidateTreeMetadata validates the tree metadata and updates version if needed.
func WriteKeyToFile ¶
WriteKeyToFile writes the formatted key to the target path, either creating a new file or appending to existing one.
Types ¶
type DecryptOpts ¶
type DecryptOpts struct {
Cipher sops.Cipher
InputStore sops.Store
OutputStore sops.Store
InputPath string
ReadFromStdin bool
IgnoreMAC bool
Extract []any
KeyServices []keyservice.KeyServiceClient
DecryptionOrder []string
}
DecryptOpts contains all options needed for the decryption operation.
type EditExampleOpts ¶
type EditExampleOpts struct {
EditOpts
EncryptConfig
InputStoreWithExample StoreWithExample
}
EditExampleOpts combines EditOpts with encryption configuration for creating and editing example files.
type EditOpts ¶
type EditOpts struct {
Cipher sops.Cipher
InputStore sops.Store
OutputStore sops.Store
InputPath string
IgnoreMAC bool
KeyServices []keyservice.KeyServiceClient
DecryptionOrder []string
ShowMasterKeys bool
}
EditOpts contains all options needed for the edit operation.
type EncryptConfig ¶
type EncryptConfig struct {
UnencryptedSuffix string
EncryptedSuffix string
UnencryptedRegex string
EncryptedRegex string
UnencryptedCommentRegex string
EncryptedCommentRegex string
MACOnlyEncrypted bool
KeyGroups []sops.KeyGroup
GroupThreshold int
}
EncryptConfig holds configuration options for SOPS encryption. It defines patterns for which values should be encrypted/unencrypted, key groups for encryption, and Shamir secret sharing threshold.
type EncryptOpts ¶
type EncryptOpts struct {
EncryptConfig
Cipher sops.Cipher
InputStore sops.Store
OutputStore sops.Store
InputPath string
ReadFromStdin bool
KeyServices []keyservice.KeyServiceClient
}
EncryptOpts contains all options needed for the encryption operation. It combines encryption configuration with runtime parameters like cipher, stores, and key services.
type FileAlreadyEncryptedError ¶
type FileAlreadyEncryptedError struct{}
FileAlreadyEncryptedError indicates that a file already contains SOPS metadata and cannot be re-encrypted without first decrypting it.
func (*FileAlreadyEncryptedError) Error ¶
func (err *FileAlreadyEncryptedError) Error() string
type RunEditorUntilOkOpts ¶
type RunEditorUntilOkOpts struct {
TmpFileName string
OriginalHash []byte
InputStore sops.Store
ShowMasterKeys bool
Tree *sops.Tree
Logger *logrus.Logger
}
RunEditorUntilOkOpts contains options for the editor loop.
type StoreWithExample ¶
StoreWithExample is an interface for stores that can emit example files.
Source Files