RequestSeal.JOSE.KeyManagement (RequestSeal v0.2.0)

Copy Markdown View Source

Custodian-side RFC 7518 key wrapping primitives over OTP.

wrap/4 returns {:ok, %{encrypted_key: bytes, header: map}}; unwrap/4 returns {:ok, bytes}. Both return {:error, JOSE.Error} on failure. These functions consume operation-local descriptors only: {:rsa, otp_key}, {:aes, kek}, {:cek, bytes}. RSA wrapping takes an OTP public key; unwrapping takes an OTP private key. Private keys and symmetric material remain the caller custodian's responsibility.

RSA-OAEP uses SHA-1/MGF1 SHA-1; RSA-OAEP-256 uses SHA-256/MGF1 SHA-256, both with an empty label. RSA encrypted keys must equal the modulus width, and private RSA CRT components are checked. RSA keys are 2048–8192 bits. A128GCMKW/A256GCMKW use 16/32-byte KEKs, fresh 12-byte IVs, empty AAD, and 16-byte tags. The returned iv/tag header additions must be protected. Received widths reject before OTP. dir produces an empty encrypted key and requires the supplied CEK to equal the direct key. JOSE envelopes enforce the content cipher's CEK width; primitives also support published unwrap stages belonging to other content algorithms without enabling those algorithms.

Summary

Functions

unwrap(alg, bytes, header, material)

@spec unwrap(binary(), binary(), map(), tuple()) ::
  {:ok, binary()} | {:error, RequestSeal.JOSE.Error.t()}

wrap(alg, bytes, header, material)

@spec wrap(binary(), binary(), map(), tuple()) ::
  {:ok, map()} | {:error, RequestSeal.JOSE.Error.t()}