Interface: KeyWrap
Defined in: packages/key-wrap/src/port.ts:27
The port through which a module protects a data key at rest (chapter 24).
Two operations and no more: there is deliberately no export of a key encryption key, no generate-and-return of one, and no listing. A data key is generated by the caller, wrapped, and stored with KeyWrap.activeKekId beside it, so a stored value always says which key and which custody unwraps it.
There are two adapters: the software one, and the hardware one behind KeyCustodian
(slice 3). Both preserve, and a third must: a key id names its custody (soft:v1:...,
hsm:v1:<token>:...), and an id the adapter does not hold is unknown_kek, never a
guess; unwrap of a damaged value is unwrap_failed, never partial output; a custody
that could not be asked is custody_unavailable, never unwrap_failed; and neither
operation logs, returns or throws key material. Both are asynchronous because the
hardware adapter waits on a token, which is why a caller must never invoke them
inside a database transaction (28, section 3).
Properties
activeKekId
readonlyactiveKekId:string
Defined in: packages/key-wrap/src/port.ts:32
The id under which new data keys are wrapped. Not an operation: it names the key the adapter is currently configured to wrap under, and holds no secret.
Methods
unwrap()
unwrap(
kekId,wrapped):Promise<Uint8Array<ArrayBufferLike>>
Defined in: packages/key-wrap/src/port.ts:54
Recovers a data key.
Parameters
kekId
string
The id stored beside wrapped, unchanged.
wrapped
Uint8Array
What KeyWrap.wrap returned.
Returns
Promise<Uint8Array<ArrayBufferLike>>
The data key. The caller owns it and should not log or persist it.
Throws
invalid_key_id, unknown_kek or unwrap_failed; from the
hardware adapter also custody_unavailable or custody_refused.
wrap()
wrap(
kekId,dataKey):Promise<Uint8Array<ArrayBufferLike>>
Defined in: packages/key-wrap/src/port.ts:43
Wraps a data key.
Parameters
kekId
string
A key id the adapter holds, normally KeyWrap.activeKekId.
dataKey
Uint8Array
The key to protect. The adapter does not retain or alter it.
Returns
Promise<Uint8Array<ArrayBufferLike>>
An opaque value to store, together with kekId.
Throws
invalid_key_id, unknown_kek or invalid_key; from the
hardware adapter also custody_unavailable or custody_refused.