<aside> 💡

Status: Proposal for discussion, not an adopted specification

Author: Natalie

Last updated: September 22, 2026

Reviewed by:

• Kuba - September 21, 2026 </aside>

Source: Filecoin Encryption Envelope FIP. These amendments concern the FIP, not the library API or its current implementation. They retain both encryption schemes, the FEE type string, protected application metadata, and envelope ‖ ciphertext storage. Chunk count is still derived from ciphertext length; no stored count is added. For chunked objects whose length is known before encryption, amendment 4 adds an optional protected plaintext_length commitment.

The aim is to correct the FIP and state its format choices, not repeat the COSE specifications. MUST and SHOULD below describe proposed requirements.

Each amendment identifies a correction to an error, a clarification of unclear wording, or a profile decision that the FIP authors need to approve. A profile is the subset of COSE rules and options chosen for FEE. In proposed requirements, MUST means required, SHOULD or RECOMMENDED means recommended with justified exceptions, and MAY means permitted. These words do not mean the current FIP already contains those rules.

COSE terms used here

COSE defines containers for encrypted data and the information needed to use it. FEE needs only part of COSE, not every message type or algorithm.

• CBOR and CDDL: CBOR is the binary format used for the envelope. CDDL describes the allowed structure and types. In examples, bstr is a byte string, tstr is text, and h'' is a byte string containing no bytes.
• Headers and labels: headers are maps of parameters. Their keys are called labels; for example, label 1 means alg, the algorithm identifier.
• Protected and unprotected headers: both are readable without a key. Protected headers are included in a cryptographic calculation so changes can be detected. They are not encrypted. COSE also calls these two maps “buckets.”
• Content and recipient layers: the content layer encrypts the file with the content encryption key (CEK). A recipient record describes how to obtain that CEK, usually by decrypting a wrapped copy with a key-encryption key (KEK). Recipient headers have their own rules, separate from content headers.
• Authentication tag and AAD: AES-GCM produces encrypted bytes and a tag used to detect tampering. Additional authenticated data (AAD) is checked by the tag but is not encrypted. This combination is called authenticated encryption with associated data (AEAD). COSE calls the structure used to build content AAD Enc_structure.
• Key derivation: a key derivation function (KDF) produces a key from secret input and context. COSE_KDF_Context is COSE’s structure for that context. It is different from content AAD.

1. Correct recipient header placement

Affects Multi-Recipient Support, lines 327–339.

The FIP currently requires alg in every recipient's protected header. That placement is wrong for A256KW, but useful for ECDH-ES+A256KW because the protected bytes are part of its key derivation. Replace the blanket rule with:

Each recipient MUST identify its key-distribution algorithm using alg. Header placement and processing MUST follow that algorithm's COSE requirements.

For A256KW (-5), the recipient protected field MUST be a zero-length byte string, and alg MUST be in the unprotected map. A key identifier kid (label 4, a byte string) is RECOMMENDED when needed to identify the wrapping key (key-encryption key).

For FEE recipients using ECDH-ES+A256KW (-31), alg MUST be in the recipient protected map and MUST NOT be in its unprotected map. The original serialized protected bytes MUST be included in COSE_KDF_Context as required by RFC 9052 §8.5.5 and RFC 9053 §5.2. The content envelope's protected bytes cannot be used in their place.

The two recipient forms look like this in readable CBOR notation: