module JOSE::JWS

Overview

JWS (JSON Web Signature) compact serialization (RFC 7515).

alg — Signature Algorithm:

Algorithm defaults inferred from key type when not provided: EC → "ES256", RSA → "RS256", oct → "HS256", OKP → "EdDSA".

Defined in:

jose/jws.cr

Class Method Summary

Class Method Detail

def self.peek_payload(compact : String) : String #

Returns the decoded payload string from compact without verifying.


[View source]
def self.peek_protected(compact : String) : Hash(String, JSON::Any) #

Returns the decoded protected header from compact without verifying.


[View source]
def self.peek_signature(compact : String) : Bytes #

Returns the raw signature bytes from compact without verifying.


[View source]
def self.sign(jwk : JWK, plain_text : String, header_overrides : Hash(String, JSON::Any) | Nil = nil) : SignedBinary #

Signs plain_text with jwk and returns a compact SignedBinary.

The algorithm is taken from header_overrides["alg"] when present; otherwise it is inferred from jwk's key type (see module doc for defaults). header_overrides may also carry "kid" and any custom header fields.

jwk = JOSE::JWK.generate_key({"kty" => JSON::Any.new("EC"), "crv" => JSON::Any.new("P-256")})
signed = JOSE::JWS.sign(jwk, "{\"sub\":\"alice\"}")
valid, payload = JOSE::JWS.verify(jwk, signed)

[View source]
def self.sign_json(jwk : JWK, plain_text : String, protected_overrides : Hash(String, JSON::Any) | Nil = nil, unprotected : Hash(String, JSON::Any) | Nil = nil) : String #

Signs plain_text and returns a JWS Flattened JSON Serialization.

Fields in protected_overrides go into the signed protected header. Fields in unprotected go into the unsigned per-signature header. When unprotected carries "alg" the protected header will contain no "alg" entry (§4.7 style — protected header omitted entirely if it stays empty). The kid from jwk is added to the protected header when neither protected_overrides nor unprotected already carry it.


[View source]
def self.verify(jwk : JWK, signed : String | SignedBinary, detached : String | Nil = nil) : Tuple(Bool, String) #

Verifies a compact JWS using jwk.

signed may be a raw compact serialization String or a SignedBinary. Returns {valid, payload} where valid is true when the signature checks out and payload is the decoded payload string regardless of validity. Raises ArgumentError if the token does not have three parts.

Pass detached (the original plain-text payload) when verifying a token with detached content (RFC 7515 §7): the compact token must have an empty middle segment (header..signature) and the caller supplies the payload out-of-band. Raises ArgumentError if detached is given but the token's payload segment is non-empty.


[View source]
def self.verify_json(jwk : JWK, json : String) : Tuple(Bool, String) #

Verifies a JWS JSON Serialization using jwk.

Accepts both the flattened form {"payload":…,"protected":…,"header":…,"signature":…} and the general form {"payload":…,"signatures":[…]}. For the general form every signature entry is tried in order; {true, payload} is returned on the first entry that verifies against jwk. Returns {false, payload} when no entry verifies. The alg value is taken from the protected header first, then from the unprotected header.


[View source]