$ciphers
$ciphers : list<\Drupal\strata\Crypto\CipherInterface>
The ciphers, in the order they are tried.
Seals with the active key and opens with whichever key on the ring works.
A drop-in CipherInterface, so nothing in the pipeline knows a rotation is in progress. The object
store, the segment writer and the verifier all take a cipher and this is one.
Sealing only ever uses the active key. A rotation is only finished when nothing is left sealed under a retired key, and sealing with anything but the newest key would mean the rotation could never finish.
The last key that opened something is remembered, because that is the only way to tell a frame
that is up to date from one that predates the rotation. There is no key fingerprint in the frame
format, so the fact that a retired key was the one that worked IS the signal, and
KeyRotation reads it to measure how much of the store still needs the old key.
That memory is per-instance and not thread-safe in any sense; it describes the most recent open()
on this object and is meaningless after any other call. Read it immediately or not at all.
A failure to open reports the cipher's own error, not a guess about the key. A wrong key and a corrupt byte both fail the Poly1305 tag identically, so claiming the key is at fault would be a conclusion drawn from an observation that does not support it.
$ciphers : list<\Drupal\strata\Crypto\CipherInterface>
The ciphers, in the order they are tried.
$ring : \Drupal\strata\Crypto\KeyRing
seal(string $plain, string $associated = '') : string
Seals a frame.
| string | $plain | The bytes to seal. An empty string seals to an empty string, so an absent payload never becomes a non-empty frame. |
| string | $associated | Additional authenticated data - bound to the ciphertext but not encrypted. Strata passes the frame's own digest, which is what makes a frame moved to a different key in the bucket fail to open rather than open as the wrong content. |
The sealed bytes, including whatever nonce and tag the implementation needs to open them.
open(string $sealed, string $associated = '') : string
Opens a sealed frame.
| string | $sealed | The sealed bytes. |
| string | $associated | The same additional authenticated data used to seal. |
When no key on the ring opens the value, which cannot be told apart from corruption.
The original bytes.