repository·main·Indexed 12 days ago
https://github.com/getsops/sopsA tool for encrypting, decrypting, and managing secrets in files. It supports multiple formats including YAML, JSON, Dotenv, Ini, and Binary, and implements Shamir's Secret Sharing using GF(2^8) finite field arithmetic. Key features include the `EncryptTree` and `DecryptTree` functions, integration with AWS KMS, and an `exec` subcommand for passing plaintext secrets to commands via temporary files or environment variables.
SOPS is an editor for encrypted files. It allows you to manage secrets within structured files by encrypting only the values while keeping the keys and structure visible (depending on the format).
Supported File Formats:
Supported Encryption Backends:
Lagrange interpolation is the mathematical method used to reconstruct the original polynomial from a set of points (parts).
Given n points (x_0, y_0), ..., (x_{n-1}, y_{n-1}), there is exactly one polynomial of degree n-1 that passes through all of them. The interpolation formula is:
L(x) = sum from j=0 to j=(n-1) of {y_j * l_j(x)}
where l_j(x) = product from m=0 to m=(n-1) except when m=j of {(x - x_m)/(x_j - x_m)}.
In the context of Shamir's Secret Sharing, this allows a user to input the collected parts to find the polynomial's constant term, which is the secret.
To prevent information leakage and ensure uniform sampling of coefficients, this implementation uses finite field arithmetic instead of standard integer arithmetic.
Specifically, it uses GF(2^8) with 229 as the generator.
Key characteristics:
Shamir's Secret Sharing is a method for splitting a secret into multiple parts such that a minimum number of parts (the threshold) is required to reconstruct the original secret.
It works by representing the secret as the constant term (the y-intercept) of a polynomial of degree threshold - 1.
threshold can be used to reconstruct the original polynomial via Lagrange interpolation. Once the polynomial is reconstructed, the secret is recovered from the constant term.Example: If you have a secret and want a threshold of 2, you use a polynomial of degree 1 (a line: y = ax + S). You generate parts by picking random a values and calculating y for different x values. Any 2 points will allow you to solve for S.
Depending on your environment, you need different access levels to handle the encrypted files:
Developers must have access to the underlying encryption keys:
In a public CI environment where you cannot access real secrets, you can simulate the configuration by copying the encrypted directory to the decrypted directory. This preserves the file structure (including the sops metadata key) without revealing actual secret values. You can use the CONFIG_COPY_ONLY environment variable to use symbolic links instead of performing actual decryption.
For environments requiring real secret data, you should follow production deployment patterns (see below).
# For public CI testing using symbolic links instead of decryption
CONFIG_COPY_ONLY=TRUE bin/decrypt-config.shThis example demonstrates a pattern for storing sensitive information (secrets) directly alongside related non-sensitive information within a project. To run the example from the sops root directory, you must first import the provided test key, navigate to the example directory, decrypt the secrets, and then execute the main script.
# From the `sops` root directory
# Import the test key
gpg --import pgp/sops_functional_tests_key.asc
# Navigate to our example directory
cd examples/per_file
# Decrypt our secrets
bin/decrypt-config.sh
# Optionally edit a secret
# bin/edit-secret.sh config.enc/static_github.json
# Run our script
python main.pyThe example provides helper scripts to manage the lifecycle of the encrypted secrets file:
bin/decrypt-config.sh to decrypt the catch-all file config/secret.enc.json into config/secret.json.bin/edit-secret.sh config/secret.enc.json to edit a secret and automatically re-encrypt it.# Decrypt secrets
bin/decrypt-config.sh
# Edit a secret (and re-encrypt)
bin/edit-secret.sh config/secret.enc.jsonWhen running tests in a public CI environment where you cannot use real secrets, you can simulate the secret structure by copying the encrypted file to the decrypted filename. This preserves the structure (including the sops key) without revealing actual secret data.
Use the CONFIG_COPY_ONLY=TRUE environment variable with the decryption script to perform a simple cp instead of running sops decrypt.
CONFIG_COPY_ONLY=TRUE bin/decrypt-config.shThis example demonstrates a project configuration where all secrets are stored in a single file (e.g., config/secret.enc.json). To run the full workflow from the sops root directory, import the test key, navigate to the example directory, decrypt the secrets, and run the main script.
# From the `sops` root directory
# Import the test key
gpg --import tests/sops_functional_tests_key.asc
# Navigate to our example directory
cd examples/all_in_one
# Decrypt our secrets
bin/decrypt-config.sh
# Run a script that uses our decrypted secrets
python main.pyFor production environments, there are two primary patterns for handling SOPS-encrypted secrets:
.tar.gz) in a private CI that already contains the decrypted secrets, then deploy that archive to the service.When moving from development to production, use one of the following two patterns to handle encrypted secrets:
.tar.gz) within a private CI environment that contains the already-decrypted secrets, then deploy that archive to your service.sops decrypt step during the deployment process on that machine.