Skip to main content

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​

readonly activeKekId: 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.