0.1.0-preview
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.
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.
On keyring initialization, a keyring MUST define at least one of the following:
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 children keyrings is empty, a generator keyring MUST be defined for the keyring.
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.
If this keyring has a generator keyring, this keyring MUST first call that 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 children keyrings, the keyring MUST call OnEncrypt. The encryption materials inputted into OnEncrypt is the input encryption materials if this is the first OnEncrypt call. If this is not the first OnEncrypt call, the encryption materials inputted is the encryption materials outputted 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.
If the input decryption materials contains a plaintext data key, OnDecrypt MUST immediately return the unmodified decryption materials.
Otherwise, OnDecrypt MUST attempt to decrypt the encrypted data keys in the input decryption materials using it's children keyrings and, if it is specified, generator keyring. It MUST attempt to decrypt using these keyrings until it either succeeds in decryption, or it has no more child keyrings or generator keyring to attempt decryption with. If a generator keyring is specified, it MUST be used first.
For each keyring to be used for decryption, the multi-keyring MUST call that keyring's OnDecrypt using the unmodified decryption materials and input encrypted data key list as input. If OnDecrypt returns decryption materials containing a plaintext data key, the keyring MUST immediately return the modified decryption materials.
If, after calling OnDecrypt on every one of this keyring's children keyrings (and possibly the generator keyring), the decryption materials still do not contain a plaintext data key:
- If none of the above OnDecrypt calls failed, the keyring MUST return the unmodified decryption materials.
- If at least one of the above OnDecrypt calls failed, OnDecrypt MUST also fail, and MUST not modify the input decryption materials.
TODO: what security guarantees does this keyring have? (#12)
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 children 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.