The Sops Document Format
draft-sops-latest

Abstract

The Sops document format stores configuration files in a structured format that protect the confidentiality of values and the integrity of the entire document.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on December 13, 2019.

Copyright Notice

Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

• 1. Introduction
• 2. Conventions and Terminology
• 3. Sops Design Rationale and Overview (#sops-rational)
• 3.1. Document key encryption (#doc-key-encrypt)
• 4. Document Encoding and Decoding (#encoding-decoding)
• 5. Document Key Splitting (#document-key-splitting)
• 6. Contributors
• Author's Address

1. Introduction

The primary goal of Sops is to provide a secure and practical way to manage configuration files. Its intended audience is operational groups that engineer deployment systems for their infrastructure.

The Sops document format is best used with structured file formats, such as JSON or YAML. In those formats, Sops guarantees the confidentiality of configuration values stored in a given file, but does not protect the confidentiality of the document structure. Storing the document structure in cleartext allows for better integration with infrastructure management and versions control tools.

In addition to confidentiality, Sops guarantees the integrity of a document to protect against malicious addition, removal and reordering of configuration values.

Sops is a specialized document format and is not meant to cover the confidentiality needs of the general population.

2. Conventions and Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

The following terms are used:

• document: a file that contains data requiring protection.
• document key: a symetric key that encrypts and decrypts the values of a document.
• master key: a symetric or asymetric key that encrypts and decrypts a document key a one of its fragment.
• key group: a set of master keys that encrypt or decrypt a document key or one of its fragment.
• threshold: a configurable number of key groups needed to recover a document key.
• mac: a message authentication code that protects the integrity of a document.

3. Sops Design Rationale and Overview (#sops-rational)

The operation of internet services requires operational teams to manage configuration files that contain sensitive information, such as cryptographic keys and password. Leaking or modifying this information can have critical consequence on services and their users, and it is thus a primary concern of operation teams to maintain the security of configuration files.

The Sops document format provides confidentiality and integrity guarantees to safely manage configuration files while offering features that facilitate integration with operational practices, such as:

• integration with YAML and JSON format. Sops documents conserve the structure of documents created in YAML and JSON formats.
• integration with versions control systems (VCS). When used with structured document formats, such as YAML and JSON, Sops exposes the document structure in cleartext and only encrypts leaf values, allowing VCS to display meaningful diffs and handle merge conflicts.
• flexible document key management. Each file is protected by a document key that is itself protected by one or several master keys. The Sops document format is extensible to allows for master keys format to be added easily as the industry provides new methods key management. # Sops Metadata (#sops-metadata)

foo

3.1. Document key encryption (#doc-key-encrypt)

At a minimum, implementations of the Sops document format SHOULD support master key protocols OpenPGP, RSA OAEP and AES256-GCM.

4. Document Encoding and Decoding (#encoding-decoding)

foo

5. Document Key Splitting (#document-key-splitting)

foo

6. Contributors

Many people have contributed to the Sops open source initiative and they are acknowledged on github.com/mozilla/sops.

In addition, we would like to thank Adrian Utrilla, AJ Bahnken, Jeremy Orem and Daniel Thorn from Mozilla.

Author's Address