sops

package module
v3.13.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 16, 2026 License: MPL-2.0 Imports: 23 Imported by: 28

README 

SOPS: Secrets OPerationS
========================

**SOPS** is an editor of encrypted files that supports YAML, JSON, ENV, INI and BINARY
formats and encrypts with AWS KMS, GCP KMS, Azure Key Vault, HuaweiCloud KMS, age, and PGP.
(`demo <https://www.youtube.com/watch?v=YTEVyLXFiq0>`_)

.. image:: https://i.imgur.com/X0TM5NI.gif

------------

.. image:: https://pkg.go.dev/badge/github.com/getsops/sops/v3.svg
    :target: https://pkg.go.dev/github.com/getsops/sops/v3

Documentation
-------------

You can find the SOPS documentation on `getsops.io <https://getsops.io/>`_ under `"Docs" <https://getsops.io/docs/>`_.

Security
--------

Please report any security issues privately using `GitHub's advisory form <https://github.com/getsops/sops/security/advisories>`_.

License
-------

Mozilla Public License Version 2.0

Authors
-------

SOPS was initially launched as a project at Mozilla in 2015 and has been
graciously donated to the CNCF as a Sandbox project in 2023, now under the
stewardship of a `new group of maintainers <https://github.com/getsops/community/blob/main/MAINTAINERS.md>`_.

The original authors of the project were:

* Adrian Utrilla @autrilla
* Julien Vehent @jvehent

Furthermore, the project has been carried for a long time by AJ Bahnken @ajvb,
and had not been possible without the contributions of numerous `contributors <https://github.com/getsops/sops/graphs/contributors>`_.

Credits
-------

SOPS was inspired by `hiera-eyaml <https://github.com/TomPoulton/hiera-eyaml>`_,
`credstash <https://github.com/LuminalOSS/credstash>`_,
`sneaker <https://github.com/codahale/sneaker>`_,
`password store <http://www.passwordstore.org/>`_ and too many years managing
PGP encrypted files by hand...

-----

.. image:: docs/images/cncf-color-bg.svg
   :width: 400
   :alt: CNCF Sandbox Project

**We are a** `Cloud Native Computing Foundation <https://cncf.io>`_ **sandbox project.**

Documentation

Overview

Package sops manages JSON, YAML and BINARY documents to be encrypted or decrypted.

This package should not be used directly. Instead, Sops users should install the command line client via `go get -u github.com/getsops/sops/v3/cmd/sops`, or use the decryption helper provided at `github.com/getsops/sops/v3/decrypt`.

We do not guarantee API stability for any package other than `github.com/getsops/sops/v3/decrypt`.

A Sops document is a Tree composed of a data branch with arbitrary key/value pairs and a metadata branch with encryption and integrity information.

In JSON and YAML formats, the structure of the cleartext tree is preserved, keys are stored in cleartext and only values are encrypted. Keeping the keys in cleartext provides better readability when storing Sops documents in version controls, and allows for merging competing changes on documents. This is a major difference between Sops and other encryption tools that store documents as encrypted blobs.

In BINARY format, the cleartext data is treated as a single blob and the encrypted document is in JSON format with a single `data` key and a single encrypted value.

Sops allows operators to encrypt their documents with multiple master keys. Each of the master key defined in the document is able to decrypt it, allowing users to share documents amongst themselves without sharing keys, or using a PGP key as a backup for KMS.

In practice, this is achieved by generating a data key for each document that is used to encrypt all values, and encrypting the data with each master key defined. Being able to decrypt the data key gives access to the document.

The integrity of each document is guaranteed by calculating a Message Authentication Code (MAC) that is stored encrypted by the data key. When decrypting a document, the MAC should be recalculated and compared with the MAC stored in the document to verify that no fraudulent changes have been applied. The MAC covers keys and values as well as their ordering.

Index

Constants

View Source 
const DefaultUnencryptedSuffix = "_unencrypted"

DefaultUnencryptedSuffix is the default suffix a TreeItem key has to end with for sops to leave its Value unencrypted

View Source 
const MacMismatch = sopsError("MAC mismatch")

MacMismatch occurs when the computed MAC does not match the expected ones

View Source 
const MetadataNotFound = sopsError("sops metadata not found")

MetadataNotFound occurs when the input file is malformed and doesn't have sops metadata in it

Variables

View Source 
var DefaultDecryptionOrder = []string{age.KeyTypeIdentifier, pgp.KeyTypeIdentifier}
View Source 
var MACOnlyEncryptedInitialization = []byte{0x8a, 0x3f, 0xd2, 0xad, 0x54, 0xce, 0x66, 0x52, 0x7b, 0x10, 0x34, 0xf3, 0xd1, 0x47, 0xbe, 0xb, 0xb, 0x97, 0x5b, 0x3b, 0xf4, 0x4f, 0x72, 0xc6, 0xfd, 0xad, 0xec, 0x81, 0x76, 0xf2, 0x7d, 0x69}

MACOnlyEncryptedInitialization is a constant and known sequence of 32 bytes used to initialize MAC which is computed only over values which end up encrypted. That assures that a MAC with the setting enabled is always different from a MAC with this setting disabled. The following numbers are taken from the output of `echo -n sops | sha256sum` (shell) or `hashlib.sha256(b'sops').hexdigest()` (Python).

Functions

func EmitAsMap 

func EmitAsMap(in TreeBranches) (map[string]interface{}, error)

EmitAsMap will emit the tree branches as a map. This is used by the publish command for writing decrypted trees to various destinations. Should only be used for outputting to data structures in code.

func ToBytes 

func ToBytes(in interface{}) ([]byte, error)

ToBytes converts a string, int, float or bool to a byte representation.

Types

type CheckEncrypted added in v3.9.0 

type CheckEncrypted interface {
	HasSopsTopLevelKey(TreeBranch) bool
}

CheckEncrypted is the interface for testing whether a branch contains sops metadata. This is used to check whether a file is already encrypted or not.

type Cipher 

type Cipher interface {
	// Encrypt takes a plaintext, a key and additional data and returns the plaintext encrypted with the key, using the
	// additional data for authentication
	Encrypt(plaintext interface{}, key []byte, additionalData string) (ciphertext string, err error)
	// Encrypt takes a ciphertext, a key and additional data and returns the ciphertext encrypted with the key, using
	// the additional data for authentication
	Decrypt(ciphertext string, key []byte, additionalData string) (plaintext interface{}, err error)
}

Cipher provides a way to encrypt and decrypt the data key used to encrypt and decrypt sops files, so that the data key can be stored alongside the encrypted content. A Cipher must be able to decrypt the values it encrypts.

type Comment 

type Comment struct {
	Value  string
	Inline bool
}

Comment represents a comment in the sops tree for the file formats that actually support them.

type EncryptedFileEmitter 

type EncryptedFileEmitter interface {
	EmitEncryptedFile(Tree) ([]byte, error)
}

EncryptedFileEmitter is the interface for emitting encrypting files. It provides a way to emit encrypted files from the internal SOPS representation.

type EncryptedFileLoader 

type EncryptedFileLoader interface {
	LoadEncryptedFile(in []byte) (Tree, error)
}

EncryptedFileLoader is the interface for loading of encrypted files. It provides a way to load encrypted SOPS files into the internal SOPS representation. Because it loads encrypted files, the returned data structure already contains all SOPS metadata.

type KeyGroup 

type KeyGroup []keys.MasterKey

KeyGroup is a slice of SOPS MasterKeys that all encrypt the same part of the data key

type Metadata 

type Metadata struct {
	LastModified              time.Time
	UnencryptedSuffix         string
	EncryptedSuffix           string
	UnencryptedRegex          string
	EncryptedRegex            string
	UnencryptedCommentRegex   string
	EncryptedCommentRegex     string
	MessageAuthenticationCode string
	MACOnlyEncrypted          bool
	Version                   string
	KeyGroups                 []KeyGroup
	// ShamirThreshold is the number of key groups required to recover the
	// original data key
	ShamirThreshold int
	// DataKey caches the decrypted data key so it doesn't have to be decrypted with a master key every time it's needed
	DataKey []byte
}

Metadata holds information about a file encrypted by sops

func (Metadata) GetDataKey 

func (m Metadata) GetDataKey() ([]byte, error)

GetDataKey retrieves the data key from the first MasterKey in the Metadata's KeySources that's able to return it, using the local KeyService

func (*Metadata) GetDataKeyWithKeyServices 

func (m *Metadata) GetDataKeyWithKeyServices(svcs []keyservice.KeyServiceClient, decryptionOrder []string) ([]byte, error)

GetDataKeyWithKeyServices retrieves the data key, asking KeyServices to decrypt it with each MasterKey in the Metadata's KeySources until one of them succeeds.

func (*Metadata) MasterKeyCount 

func (m *Metadata) MasterKeyCount() int

MasterKeyCount returns the number of master keys available

func (*Metadata) UpdateMasterKeys 

func (m *Metadata) UpdateMasterKeys(dataKey []byte) (errs []error)

UpdateMasterKeys encrypts the data key with all master keys

func (*Metadata) UpdateMasterKeysWithKeyServices 

func (m *Metadata) UpdateMasterKeysWithKeyServices(dataKey []byte, svcs []keyservice.KeyServiceClient) (errs []error)

UpdateMasterKeysWithKeyServices encrypts the data key with all master keys using the provided key services

type PlainFileEmitter 

type PlainFileEmitter interface {
	EmitPlainFile(TreeBranches) ([]byte, error)
}

PlainFileEmitter is the interface for emitting plain text files. It provides a way to emit plain text files from the internal SOPS representation so that they can be shown

type PlainFileLoader 

type PlainFileLoader interface {
	LoadPlainFile(in []byte) (TreeBranches, error)
}

PlainFileLoader is the interface for loading of plain text files. It provides a way to load unencrypted files into SOPS. Because the files it loads are unencrypted, the returned data structure does not contain any metadata.

type SingleValueStore added in v3.11.0 

type SingleValueStore interface {
	Store
	IsSingleValueStore() bool
}

SingleValueStore is the interface for determining whether a store uses only one single key and no comments. This is basically identifying the binary store.

type SopsKeyNotFound added in v3.9.0 

type SopsKeyNotFound struct {
	Key interface{}
	Msg string
}

func (*SopsKeyNotFound) Error added in v3.9.0 

func (e *SopsKeyNotFound) Error() string

type Store 

type Store interface {
	EncryptedFileLoader
	PlainFileLoader
	EncryptedFileEmitter
	PlainFileEmitter
	ValueEmitter
	CheckEncrypted
	Name() string
}

Store is used to interact with files, both encrypted and unencrypted.

type Tree 

type Tree struct {
	Metadata Metadata
	Branches TreeBranches
	// FilePath is the path of the file this struct represents
	FilePath string
}

Tree is the data structure used by sops to represent documents internally

func (Tree) Decrypt 

func (tree Tree) Decrypt(key []byte, cipher Cipher) (string, error)

Decrypt walks over the tree and decrypts all values with the provided cipher, except those whose key ends with the UnencryptedSuffix specified on the Metadata struct, those not ending with EncryptedSuffix, if EncryptedSuffix is provided (by default it is not), those not matching EncryptedRegex, if EncryptedRegex is provided (by default it is not), or those matching UnencryptedRegex, if UnencryptedRegex is provided (by default it is not). If decryption is successful, it returns the MAC for the decrypted tree (all values if MACOnlyEncrypted is false, or only over values which end up decrypted if MACOnlyEncrypted is true).

func (Tree) Encrypt 

func (tree Tree) Encrypt(key []byte, cipher Cipher) (string, error)

Encrypt walks over the tree and encrypts all values with the provided cipher, except those whose key ends with the UnencryptedSuffix specified on the Metadata struct, those not ending with EncryptedSuffix, if EncryptedSuffix is provided (by default it is not), those not matching EncryptedRegex, if EncryptedRegex is provided (by default it is not), those matching UnencryptedRegex, if UnencryptedRegex is provided (by default it is not), those with their comment not matching EncryptedCommentRegex, if EncryptedCommentRegex is provided (by default it is not), or those with their comment matching UnencryptedCommentRegex, if UnencryptedCommentRegex is provided (by default it is not). If encryption is successful, it returns the MAC for the encrypted tree (all values if MACOnlyEncrypted is false, or only over values which end up encrypted if MACOnlyEncrypted is true).

func (Tree) GenerateDataKey 

func (tree Tree) GenerateDataKey() ([]byte, []error)

GenerateDataKey generates a new random data key and encrypts it with all MasterKeys.

func (*Tree) GenerateDataKeyWithKeyServices 

func (tree *Tree) GenerateDataKeyWithKeyServices(svcs []keyservice.KeyServiceClient) ([]byte, []error)

GenerateDataKeyWithKeyServices generates a new random data key and encrypts it with all MasterKeys.

type TreeBranch 

type TreeBranch []TreeItem

TreeBranch is a branch inside sops's tree. It is a slice of TreeItems and is therefore ordered

func (TreeBranch) Equals added in v3.10.0 

func (branch TreeBranch) Equals(other TreeBranch) bool

Compare a branch with another one

func (TreeBranch) Set 

func (branch TreeBranch) Set(path []interface{}, value interface{}) (TreeBranch, bool)

Set sets a value on a given tree for the specified path

func (TreeBranch) Truncate 

func (branch TreeBranch) Truncate(path []interface{}) (interface{}, error)

Truncate truncates the tree to the path specified

func (TreeBranch) Unset added in v3.9.0 

func (branch TreeBranch) Unset(path []interface{}) (TreeBranch, error)

Unset removes a value on a given tree from the specified path

type TreeBranches 

type TreeBranches []TreeBranch

TreeBranches is a collection of TreeBranch Trees usually have more than one branch

type TreeItem 

type TreeItem struct {
	Key   interface{}
	Value interface{}
}

TreeItem is an item inside sops's tree

type UserError 

type UserError interface {
	error
	UserError() string
}

UserError is a well-formatted error for the purpose of being displayed to the end user.

type ValueEmitter 

type ValueEmitter interface {
	EmitValue(interface{}) ([]byte, error)
}

ValueEmitter is the interface for emitting a value. It provides a way to emit values from the internal SOPS representation so that they can be shown

Source Files

View all Source files

Directories

Path Synopsis
Package aes defines a Cipher that uses 256-bit AES-GCM authenticated encryption to encrypt values the SOPS tree.
 Package aes defines a Cipher that uses 256-bit AES-GCM authenticated encryption to encrypt values the SOPS tree.
Package azkv contains an implementation of the github.com/getsops/sops/v3/keys.MasterKey interface that encrypts and decrypts the data key using Azure Key Vault with the Azure Key Vault Keys client module for Go.
 Package azkv contains an implementation of the github.com/getsops/sops/v3/keys.MasterKey interface that encrypts and decrypts the data key using Azure Key Vault with the Azure Key Vault Keys client module for Go.
cmd
sops command
sops/codes
Package codes the exit statuses returned by the sops binary
 Package codes the exit statuses returned by the sops binary
sops/common
sops/formats
sops/subcommand/exec
sops/subcommand/filestatus
sops/subcommand/groups
sops/subcommand/keyservice
sops/subcommand/publish
sops/subcommand/updatekeys
Package config provides a way to find and load SOPS configuration files
 Package config provides a way to find and load SOPS configuration files
Package decrypt is the external API other Go programs can use to decrypt SOPS files.
 Package decrypt is the external API other Go programs can use to decrypt SOPS files.
Package hckms contains an implementation of the github.com/getsops/sops/v3/keys.MasterKey interface that encrypts and decrypts the data key using HuaweiCloud KMS with the SDK for Go V3.
 Package hckms contains an implementation of the github.com/getsops/sops/v3/keys.MasterKey interface that encrypts and decrypts the data key using HuaweiCloud KMS with the SDK for Go V3.
Package keyservice implements a gRPC API that can be used by SOPS to encrypt and decrypt the data key using remote master keys.
 Package keyservice implements a gRPC API that can be used by SOPS to encrypt and decrypt the data key using remote master keys.
Package kms contains an implementation of the github.com/getsops/sops/v3.MasterKey interface that encrypts and decrypts the data key using AWS KMS with the SDK for Go V2.
 Package kms contains an implementation of the github.com/getsops/sops/v3.MasterKey interface that encrypts and decrypts the data key using AWS KMS with the SDK for Go V2.
Package pgp contains an implementation of the github.com/getsops/sops/v3.MasterKey interface that encrypts and decrypts the data key by first trying with the github.com/ProtonMail/go-crypto/openpgp package and if that fails, by calling the "gpg" binary.
 Package pgp contains an implementation of the github.com/getsops/sops/v3.MasterKey interface that encrypts and decrypts the data key by first trying with the github.com/ProtonMail/go-crypto/openpgp package and if that fails, by calling the "gpg" binary.
Package stores acts as a layer between the internal representation of encrypted files and the encrypted files themselves.
 Package stores acts as a layer between the internal representation of encrypted files and the encrypted files themselves.
dotenv
ini
json
yaml

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.