sops: go.mozilla.org/sops Index | Files | Directories

package sops

import "go.mozilla.org/sops"

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 go.mozilla.org/sops/cmd/sops`, or use the decryption helper provided at `go.mozilla.org/sops/decrypt`.

We do not guarantee API stability for any package other than `go.mozilla.org/sops/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 values 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 Access Control 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

Package Files

sops.go usererrors.go

Constants

const DefaultUnencryptedSuffix = "_unencrypted"

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

const MacMismatch = sopsError("MAC mismatch")

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

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

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

func ToBytes Uses

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

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

type Cipher Uses

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 Uses

type Comment struct {
    Value string
}

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

type EncryptedFileEmitter Uses

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 Uses

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 Uses

type KeyGroup []keys.MasterKey

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

type Metadata Uses

type Metadata struct {
    LastModified              time.Time
    UnencryptedSuffix         string
    EncryptedSuffix           string
    MessageAuthenticationCode string
    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 Uses

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 Uses

func (m Metadata) GetDataKeyWithKeyServices(svcs []keyservice.KeyServiceClient) ([]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 Uses

func (m *Metadata) MasterKeyCount() int

MasterKeyCount returns the number of master keys available

func (*Metadata) UpdateMasterKeys Uses

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

UpdateMasterKeys encrypts the data key with all master keys

func (*Metadata) UpdateMasterKeysWithKeyServices Uses

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 Uses

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 Uses

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 Store Uses

type Store interface {
    EncryptedFileLoader
    PlainFileLoader
    EncryptedFileEmitter
    PlainFileEmitter
    ValueEmitter
}

type Tree Uses

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 Uses

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 or those not ending with EncryptedSuffix, if EncryptedSuffix is provided (by default it is not). If decryption is successful, it returns the MAC for the decrypted tree.

func (Tree) Encrypt Uses

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, or those not ending with EncryptedSuffix, if EncryptedSuffix is provided (by default it is not). If encryption is successful, it returns the MAC for the encrypted tree.

func (Tree) GenerateDataKey Uses

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

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

func (*Tree) GenerateDataKeyWithKeyServices Uses

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

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

type TreeBranch Uses

type TreeBranch []TreeItem

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

func (TreeBranch) Set Uses

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

func (TreeBranch) Truncate Uses

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

Truncate truncates the tree to the path specified

type TreeBranches Uses

type TreeBranches []TreeBranch

Trees usually have more than one branch

type TreeItem Uses

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

TreeItem is an item inside sops's tree

type UserError Uses

type UserError interface {
    error
    UserError() string
}

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

type ValueEmitter Uses

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

Directories

PathSynopsis
aesPackage aes defines a Cipher that uses 256-bit AES-GCM authenticated encryption to encrypt values the SOPS tree.
azkvPackage azkv contains an implementation of the go.mozilla.org/sops/keys.MasterKey interface that encrypts and decrypts the data key using Azure Key Vault with the Azure Go SDK.
configPackage config provides a way to find and load SOPS configuration files
decryptPackage decrypt is the external API other Go programs can use to decrypt SOPS files.
gcpkms
keyservicePackage keyservice implements a gRPC API that can be used by SOPS to encrypt and decrypt the data key using remote master keys.
kmsPackage kms contains an implementation of the go.mozilla.org/sops.MasterKey interface that encrypts and decrypts the data key using AWS KMS with the AWS Go SDK.
kms/mocks
pgpPackage pgp contains an implementation of the go.mozilla.org/sops.MasterKey interface that encrypts and decrypts the data key by first trying with the golang.org/x/crypto/openpgp package and if that fails, by calling the "gpg" binary.
shamir
stores/json
stores/yaml

Package sops imports 18 packages (graph) and is imported by 9 packages. Updated 2018-11-26. Refresh now. Tools for package owners.