Provided by: libjose-dev_11-2_amd64 
NAME
jose_jws - JSON Web Signature (RFC 7515)
SYNOPSIS
Functions
json_t * jose_jws_hdr (const json_t *sig)
Merges the JOSE headers of a JWS signature object.
bool jose_jws_sig (jose_cfg_t *cfg, json_t *jws, json_t *sig, const json_t *jwk)
Creates one or more signatures in a JWS object.
jose_io_t * jose_jws_sig_io (jose_cfg_t *cfg, json_t *jws, json_t *sig, const json_t *jwk)
Creates one or more signatures in a JWS object using streaming.
bool jose_jws_ver (jose_cfg_t *cfg, const json_t *jws, const json_t *sig, const json_t
*jwk, bool all)
Verifies signatures of one or more JWKs in a JWS object.
jose_io_t * jose_jws_ver_io (jose_cfg_t *cfg, const json_t *jws, const json_t *sig, const
json_t *jwk, bool all)
Verifies signatures of one or more JWKs in a JWS object using streaming.
Detailed Description
JSON Web Signature (RFC 7515)
JSON Web Token (RFC 7519)
A JSON Web Signature (JWS) is a standard data format for expresing cryptographic
signatures in JSON. The signatures are produced using a JSON Web Key (JWK).
For example, to create a simple signature of a string using a JWK (error handling
omitted):
json_t *sig(const char *str, const json_t *jwk) {
json_auto_t *jws = json_pack("{s:o}", "payload",
jose_b64_enc(str, strlen(str)));
jose_jws_sig(NULL, jws, NULL, jwk);
return json_incref(jws);
}
Likewise, to verify this signature (again, error handling omitted):
char *ver(const json_t *jwe, const json_t *jwk) {
char *str = NULL;
size_t len = 0;
if (!jose_jws_ver(NULL, jws, NULL, jwk))
return NULL;
len = jose_b64_dec(json_object_get(jwe, "payload"), NULL, 0);
str = calloc(1, len + 1);
jose_b64_dec(json_object_get(jwe, "payload"), str, len);
return str;
}
See also:
https://tools.ietf.org/html/rfc7515
A JSON Web Token (JWT) is a standard data format for expresing claims transferred between
to parties in JSON. The JWT is wrapped in any number of Signatures (JWS) or Encryptions
(JWE).
See also:
https://tools.ietf.org/html/rfc7515
Function Documentation
json_t* jose_jws_hdr (const json_t * sig)
Merges the JOSE headers of a JWS signature object.
Parameters:
sig A JWS signature object.
Returns:
The newly allocated JOSE header.
bool jose_jws_sig (jose_cfg_t * cfg, json_t * jws, json_t * sig, const json_t * jwk)
Creates one or more signatures in a JWS object. The JWS object (jws) must contain the
'payload' property.
All signatures created will be appended to the JWS specified by jws. If the resulting JWS
(jws) would contain only a single signature, the JWS will be represented in Flattened JWS
JSON Serialization Syntax. Otherwise, it will be represented in General JWS JSON
Serialization Syntax.
If jwk contains a JWK, a single signature is created. In this case, jws must contain
either a JWS signature object template or NULL. You may specify algorithms or other
signature behaviors simply by specifying them in the JOSE headers of the JWS signature
object template as defined by RFC 7515. If a required property is missing, sensible
defaults will be used and inserted into the JOSE headers; inferring them from the JWK
(jwk) where possible.
If jwk contains an array of JWKs or a JWKSet, multiple signatures are created. In this
case, the sig parameter must contain one of the following values:
1. A JWS signature object template that will be used for all signatures. In this case, a
copy will be made for each signature and sig will not be modified in any way.
2. An array of JWS signature object templates. Each template will be used with its
corresponding JWK from jwk. If the arrays in sig and jwk are a different size, an
error will occur.
3. NULL. This has the same effect as passing NULL for each separate key.
Parameters:
cfg The configuration context (optional).
jws The JWS object.
sig The JWS signature object template(s) or NULL.
jwk The JWK(s) or JWKSet used for creating signatures.
Returns:
On success, true. Otherwise, false.
jose_io_t* jose_jws_sig_io (jose_cfg_t * cfg, json_t * jws, json_t * sig, const json_t * jwk)
Creates one or more signatures in a JWS object using streaming. This function behaves
substantially like jose_jws_sig() except:
The payload is not specified in the JWS (jws). Rather, the payload is provided using the
returned IO object. The input to the returned IO object will not be internally Base64
encoded. So you may need to prepend the IO chain with the result of jose_b64_enc_io()
(depending on your situation).
Likewise, the payload is not stored in the JWS object (jws). This allows for detached
payloads and decreases memory use for signatures over large payloads. If you would like to
attach the payload, it is your responsibility to do so manually.
Parameters:
cfg The configuration context (optional).
jws The JWS object.
sig The JWS signature object template(s) or NULL.
jwk The JWK(s) or JWKSet used for creating signatures.
Returns:
The new IO object or NULL on error.
bool jose_jws_ver (jose_cfg_t * cfg, const json_t * jws, const json_t * sig, const json_t *
jwk, bool all)
Verifies signatures of one or more JWKs in a JWS object. The JWS object (jws) must contain
the 'payload' property.
If a single JWK (jwk) is specified, the all parameter is ignored. In this case, if you
would like to verify a particular JWS signature object, you may specify it using the sig
parameter. Otherwise, you may simply pass NULL to verify any of the JWS signature objects
in the JWS object.
If jwk contains an array of JWKs or a JWKSet, the all parameter determines whether a valid
signature is required for every JWK in order to successfully validate the JWS. For
example, if you set all to false this function will succeed if a valid signature is found
for any of the provided JWKs. When using this multiple JWK signature mode, the sig
parameter must contain one of the following values:
1. A single JWS signature object to validate against all/any of the provided JWKs.
2. An array of JWS signature objects. In this case, each JWS signature object will be
mapped to its corresponding JWK from jwk. If the arrays in sig and jwk are a different
size, an error will occur.
3. NULL. This has the same effect as passing NULL for each separate key.
Parameters:
cfg The configuration context (optional).
jws The JWS object.
sig The JWS signature object(s) to verify or NULL.
jwk The JWK(s) or JWKSet used for verifying signatures.
all Whether or not to require validation of all JWKs.
Returns:
On success, true. Otherwise, false.
jose_io_t* jose_jws_ver_io (jose_cfg_t * cfg, const json_t * jws, const json_t * sig, const
json_t * jwk, bool all)
Verifies signatures of one or more JWKs in a JWS object using streaming. This function
behaves substantially like jose_jws_ver() except:
The payload is not specified in the JWS (jws). Rather, the payload is provided using the
returned IO object. The input to the returned IO object will not be internally Base64
encoded. So you may need to prepend the IO chain with the result of jose_b64_enc_io()
(depending on your situation).
Final signature verification is delayed until jose_io_t::done() returns.
Parameters:
cfg The configuration context (optional).
jws The JWS object.
sig The JWS signature object(s) to verify or NULL.
jwk The JWK(s) or JWKSet used for verifying signatures.
all Whether or not to require validation of all JWKs.
Returns:
The new IO object or NULL on error.
Author
Generated automatically by Doxygen for José from the source code.