Skip to content

Latest commit

 

History

History
149 lines (105 loc) · 7.17 KB

multi-keyring.md

File metadata and controls

149 lines (105 loc) · 7.17 KB

Multi-Keyring

Version

0.1.1

Changelog

Implementations

Overview

A keyring which combines other keyrings, allowing one OnEncrypt or OnDecrypt call to modify the encryption or decryption materials using more than one keyring.

A multi-keyring is capable of producing encrypted data keys that can be decrypted by multiple keyrings. A multi-keyring can decrypt an encrypted data key as long as the multi-keyring contains at least one keyring capable of decrypting that encrypted data key.

Definitions

Conventions used in this document

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Inputs

On keyring initialization, a keyring MUST define at least one of the following:

Generator Keyring

A keyring that can generate data keys.

This keyring MUST implement the Generate Data Key behavior during OnEncrypt. This means that this keyring MUST return encryption materials containing a plaintext data key on OnEncrypt.

If the list of child keyrings is empty, a generator keyring MUST be defined for the keyring.

Child Keyrings

A list of keyrings to be used to modify the encryption or decryption materials.

If this keyring does not have a generator keyring, this list MUST NOT be empty.

Operation

OnEncrypt

If this keyring has a generator keyring, this keyring MUST first generate a plaintext data key using the generator keyring:

  • If the input encryption materials already include a plaintext data key, OnEncrypt MUST fail.
  • This keyring MUST first call the generator keyring's OnEncrypt using the input encryption materials as input.
  • If the generator keyring fails OnEncrypt, this OnEncrypt MUST also fail.
  • If the generator keyring returns encryption materials missing a plaintext data key, OnEncrypt MUST fail.

If this keyring does not have a generator keyring, and the input encryption materials does not include a plaintext data key, OnEncrypt MUST fail.

Next, for each keyring in this keyring's list of child keyrings, the keyring MUST call OnEncrypt. The encryption materials input into OnEncrypt are the input encryption materials if this is the first OnEncrypt call. If this is not the first OnEncrypt call, the encryption materials input into OnEncrypt are the encryption materials output by the previous OnEncrypt call. If the child keyring's OnEncrypt fails, this OnEncrypt MUST also fail.

If all previous OnEncrypt calls succeeded, this keyring MUST return the encryption materials returned by the last OnEncrypt call.

OnDecrypt

If the decryption materials already contain a plaintext data key, the keyring MUST fail and MUST NOT modify the decryption materials.

Otherwise, OnDecrypt MUST first attempt to decrypt the encrypted data keys in the input decryption materials using its generator keyring. If the generator keyring is unable to decrypt the materials, the multi-keyring MUST attempt to decrypt using its child keyrings, until one either succeeds in decryption or all have failed.

For each keyring to be used for decryption, the multi-keyring MUST call that keyring's OnDecrypt using the unmodified decryption materials and the input encrypted data key list. If OnDecrypt returns decryption materials containing a plaintext data key, the multi-keyring MUST immediately return the modified decryption materials. If the child keyring's OnDecrypt call fails, the multi-keyring MUST collect the error and continue to the next keyring, if any.

If, after calling OnDecrypt on every child keyring (and possibly the generator keyring), the decryption materials still do not contain a plaintext data key, OnDecrypt MUST return a failure message containing the collected failure messages from the child keyrings.

Security Considerations

Users SHOULD examine the keyrings they include in a multi-keyring to ensure that they understand what set of keyrings will be capable of obtaining the plaintext data key from the returned set of encrypted data keys.

In more detail:

Multi-keyrings will produce a set of encrypted data keys on OnEncrypt that includes the encrypted data keys of every sub-keyring (a keyring which is either the generator keyring or a member of child keyrings) that is capable of producing encrypted data keys.

As such, any keyring that is capable of obtaining the plaintext data key from encrypted data keys produced by one of the sub-keyrings, by definition, is capable of obtaining the plaintext data key for the set of encrypted data keys the multi-keyring produces on OnEncrypt.

In typical cases, most keyrings are defined such that they are capable of decrypting the encrypted data keys they produce. As such, when including such keyrings, the multi-keyring will produce a set of encrypted data keys such that any one of the sub-keyrings is capable of obtaining the plaintext data key.