MessageSignatures (MessageSignatures v0.1.0)

Copy Markdown View Source

RFC 9421 HTTP Message Signatures: create and verify signatures over HTTP message components.

Composition with http_digest (RFC 9530): this package signs and verifies the content-digest header as a covered component. Validating that the digest matches the body is HTTPDigest.verify_content/3's job.

Summary

Functions

parse_signatures(message)

Parses the Signature-Input / Signature headers into labeled entries (in Signature-Input order) without verifying anything. Useful for inspecting multi-signature messages before selecting one to verify.

sign(message, opts)

Signs a message, returning [{"signature-input", value}, {"signature", value}].

signature_base(message, components, params \\ [])

Builds the signature base without signing.

verify(message, opts)

Verifies one signature on a message.

Functions

parse_signatures(message)

@spec parse_signatures(MessageSignatures.Message.t()) ::
  {:ok,
   [
     %{
       label: String.t(),
       params: MessageSignatures.SignatureParams.t(),
       signature: binary()
     }
   ]}
  | {:error, MessageSignatures.Error.t()}

Parses the Signature-Input / Signature headers into labeled entries (in Signature-Input order) without verifying anything. Useful for inspecting multi-signature messages before selecting one to verify.

sign(message, opts)

@spec sign(
  MessageSignatures.Message.t(),
  keyword()
) :: {:ok, [{String.t(), String.t()}]} | {:error, MessageSignatures.Error.t()}

Signs a message, returning [{"signature-input", value}, {"signature", value}].

Options: :key ({algorithm, material}, see MessageSignatures.Key), :key_id, :label (default "sig1"), :components (defaults: ["@method", "@target-uri"] for requests, ["@status"] for responses), :params (default [created: :now]), and :sf_types.

signature_base(message, components, params \\ [])

@spec signature_base(MessageSignatures.Message.t(), [String.t()], keyword()) ::
  {:ok, String.t()} | {:error, MessageSignatures.Error.t()}

Builds the signature base without signing.

Parameters use the same expansion as sign/2; when supplied here, :alg must be its IANA string because no key tuple is available to derive it.

verify(message, opts)

@spec verify(
  MessageSignatures.Message.t(),
  keyword()
) ::
  {:ok, MessageSignatures.VerifyResult.t()}
  | {:error, MessageSignatures.Error.t()}

Verifies one signature on a message.

Verification fails closed by default: requests must cover @method and @target-uri, responses must cover @status, created is required, and signatures older than 300 seconds are rejected with 30 seconds of clock skew. Relaxations, including required_components: [], must be explicit.