1
0

jose_jws.3 8.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233
  1. .TH "jose_jws" 3 "Tue May 30 2017" "José" \" -*- nroff -*-
  2. .ad l
  3. .nh
  4. .SH NAME
  5. jose_jws \- JSON Web Signature (RFC 7515)
  6. .SH SYNOPSIS
  7. .br
  8. .PP
  9. .SS "Functions"
  10. .in +1c
  11. .ti -1c
  12. .RI "json_t * \fBjose_jws_hdr\fP (const json_t *sig)"
  13. .br
  14. .RI "Merges the JOSE headers of a JWS signature object\&. "
  15. .ti -1c
  16. .RI "bool \fBjose_jws_sig\fP (jose_cfg_t *cfg, json_t *jws, json_t *sig, const json_t *jwk)"
  17. .br
  18. .RI "Creates one or more signatures in a JWS object\&. "
  19. .ti -1c
  20. .RI "\fBjose_io_t\fP * \fBjose_jws_sig_io\fP (jose_cfg_t *cfg, json_t *jws, json_t *sig, const json_t *jwk)"
  21. .br
  22. .RI "Creates one or more signatures in a JWS object using streaming\&. "
  23. .ti -1c
  24. .RI "bool \fBjose_jws_ver\fP (jose_cfg_t *cfg, const json_t *jws, const json_t *sig, const json_t *jwk, bool all)"
  25. .br
  26. .RI "Verifies signatures of one or more JWKs in a JWS object\&. "
  27. .ti -1c
  28. .RI "\fBjose_io_t\fP * \fBjose_jws_ver_io\fP (jose_cfg_t *cfg, const json_t *jws, const json_t *sig, const json_t *jwk, bool all)"
  29. .br
  30. .RI "Verifies signatures of one or more JWKs in a JWS object using streaming\&. "
  31. .in -1c
  32. .SH "Detailed Description"
  33. .PP
  34. JSON Web Signature (RFC 7515)
  35. JSON Web Token (RFC 7519)
  36. .PP
  37. 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)\&.
  38. .PP
  39. For example, to create a simple signature of a string using a JWK (error handling omitted):
  40. .PP
  41. .nf
  42. json_t *sig(const char *str, const json_t *jwk) {
  43. json_auto_t *jws = json_pack("{s:o}", "payload",
  44. jose_b64_enc(str, strlen(str)));
  45. jose_jws_sig(NULL, jws, NULL, jwk);
  46. return json_incref(jws);
  47. }
  48. .fi
  49. .PP
  50. .PP
  51. Likewise, to verify this signature (again, error handling omitted):
  52. .PP
  53. .nf
  54. char *ver(const json_t *jwe, const json_t *jwk) {
  55. char *str = NULL;
  56. size_t len = 0;
  57. if (!jose_jws_ver(NULL, jws, NULL, jwk))
  58. return NULL;
  59. len = jose_b64_dec(json_object_get(jwe, "payload"), NULL, 0);
  60. str = calloc(1, len + 1);
  61. jose_b64_dec(json_object_get(jwe, "payload"), str, len);
  62. return str;
  63. }
  64. .fi
  65. .PP
  66. .PP
  67. \fBSee also:\fP
  68. .RS 4
  69. https://tools.ietf.org/html/rfc7515
  70. .RE
  71. .PP
  72. 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)\&.
  73. .PP
  74. \fBSee also:\fP
  75. .RS 4
  76. https://tools.ietf.org/html/rfc7515
  77. .RE
  78. .PP
  79. .SH "Function Documentation"
  80. .PP
  81. .SS "json_t* jose_jws_hdr (const json_t * sig)"
  82. .PP
  83. Merges the JOSE headers of a JWS signature object\&.
  84. .PP
  85. \fBParameters:\fP
  86. .RS 4
  87. \fIsig\fP A JWS signature object\&.
  88. .RE
  89. .PP
  90. \fBReturns:\fP
  91. .RS 4
  92. The newly allocated JOSE header\&.
  93. .RE
  94. .PP
  95. .SS "bool jose_jws_sig (jose_cfg_t * cfg, json_t * jws, json_t * sig, const json_t * jwk)"
  96. .PP
  97. Creates one or more signatures in a JWS object\&. The JWS object (\fCjws\fP) must contain the 'payload' property\&.
  98. .PP
  99. All signatures created will be appended to the JWS specified by \fCjws\fP\&. If the resulting JWS (\fCjws\fP) 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\&.
  100. .PP
  101. If \fCjwk\fP contains a JWK, a single signature is created\&. In this case, \fCjws\fP 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 (\fCjwk\fP) where possible\&.
  102. .PP
  103. If \fCjwk\fP contains an array of JWKs or a JWKSet, multiple signatures are created\&. In this case, the \fCsig\fP parameter must contain one of the following values:
  104. .PP
  105. .IP "1." 4
  106. A JWS signature object template that will be used for all signatures\&. In this case, a copy will be made for each signature and \fCsig\fP will not be modified in any way\&.
  107. .IP "2." 4
  108. An array of JWS signature object templates\&. Each template will be used with its corresponding JWK from \fCjwk\fP\&. If the arrays in \fCsig\fP and \fCjwk\fP are a different size, an error will occur\&.
  109. .IP "3." 4
  110. NULL\&. This has the same effect as passing NULL for each separate key\&.
  111. .PP
  112. .PP
  113. \fBParameters:\fP
  114. .RS 4
  115. \fIcfg\fP The configuration context (optional)\&.
  116. .br
  117. \fIjws\fP The JWS object\&.
  118. .br
  119. \fIsig\fP The JWS signature object template(s) or NULL\&.
  120. .br
  121. \fIjwk\fP The JWK(s) or JWKSet used for creating signatures\&.
  122. .RE
  123. .PP
  124. \fBReturns:\fP
  125. .RS 4
  126. On success, true\&. Otherwise, false\&.
  127. .RE
  128. .PP
  129. .SS "\fBjose_io_t\fP* jose_jws_sig_io (jose_cfg_t * cfg, json_t * jws, json_t * sig, const json_t * jwk)"
  130. .PP
  131. Creates one or more signatures in a JWS object using streaming\&. This function behaves substantially like \fBjose_jws_sig()\fP except:
  132. .PP
  133. The payload is not specified in the JWS (\fCjws\fP)\&. 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 \fBjose_b64_enc_io()\fP (depending on your situation)\&.
  134. .PP
  135. Likewise, the payload is not stored in the JWS object (\fCjws\fP)\&. 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\&.
  136. .PP
  137. \fBParameters:\fP
  138. .RS 4
  139. \fIcfg\fP The configuration context (optional)\&.
  140. .br
  141. \fIjws\fP The JWS object\&.
  142. .br
  143. \fIsig\fP The JWS signature object template(s) or NULL\&.
  144. .br
  145. \fIjwk\fP The JWK(s) or JWKSet used for creating signatures\&.
  146. .RE
  147. .PP
  148. \fBReturns:\fP
  149. .RS 4
  150. The new IO object or NULL on error\&.
  151. .RE
  152. .PP
  153. .SS "bool jose_jws_ver (jose_cfg_t * cfg, const json_t * jws, const json_t * sig, const json_t * jwk, bool all)"
  154. .PP
  155. Verifies signatures of one or more JWKs in a JWS object\&. The JWS object (\fCjws\fP) must contain the 'payload' property\&.
  156. .PP
  157. If a single JWK (\fCjwk\fP) is specified, the \fCall\fP parameter is ignored\&. In this case, if you would like to verify a particular JWS signature object, you may specify it using the \fCsig\fP parameter\&. Otherwise, you may simply pass NULL to verify any of the JWS signature objects in the JWS object\&.
  158. .PP
  159. If \fCjwk\fP contains an array of JWKs or a JWKSet, the \fCall\fP parameter determines whether a valid signature is required for every JWK in order to successfully validate the JWS\&. For example, if you set \fCall\fP 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 \fCsig\fP parameter must contain one of the following values:
  160. .PP
  161. .IP "1." 4
  162. A single JWS signature object to validate against all/any of the provided JWKs\&.
  163. .IP "2." 4
  164. An array of JWS signature objects\&. In this case, each JWS signature object will be mapped to its corresponding JWK from \fCjwk\fP\&. If the arrays in \fCsig\fP and \fCjwk\fP are a different size, an error will occur\&.
  165. .IP "3." 4
  166. NULL\&. This has the same effect as passing NULL for each separate key\&.
  167. .PP
  168. .PP
  169. \fBParameters:\fP
  170. .RS 4
  171. \fIcfg\fP The configuration context (optional)\&.
  172. .br
  173. \fIjws\fP The JWS object\&.
  174. .br
  175. \fIsig\fP The JWS signature object(s) to verify or NULL\&.
  176. .br
  177. \fIjwk\fP The JWK(s) or JWKSet used for verifying signatures\&.
  178. .br
  179. \fIall\fP Whether or not to require validation of all JWKs\&.
  180. .RE
  181. .PP
  182. \fBReturns:\fP
  183. .RS 4
  184. On success, true\&. Otherwise, false\&.
  185. .RE
  186. .PP
  187. .SS "\fBjose_io_t\fP* jose_jws_ver_io (jose_cfg_t * cfg, const json_t * jws, const json_t * sig, const json_t * jwk, bool all)"
  188. .PP
  189. Verifies signatures of one or more JWKs in a JWS object using streaming\&. This function behaves substantially like \fBjose_jws_ver()\fP except:
  190. .PP
  191. The payload is not specified in the JWS (\fCjws\fP)\&. 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 \fBjose_b64_enc_io()\fP (depending on your situation)\&.
  192. .PP
  193. Final signature verification is delayed until \fBjose_io_t::done()\fP returns\&.
  194. .PP
  195. \fBParameters:\fP
  196. .RS 4
  197. \fIcfg\fP The configuration context (optional)\&.
  198. .br
  199. \fIjws\fP The JWS object\&.
  200. .br
  201. \fIsig\fP The JWS signature object(s) to verify or NULL\&.
  202. .br
  203. \fIjwk\fP The JWK(s) or JWKSet used for verifying signatures\&.
  204. .br
  205. \fIall\fP Whether or not to require validation of all JWKs\&.
  206. .RE
  207. .PP
  208. \fBReturns:\fP
  209. .RS 4
  210. The new IO object or NULL on error\&.
  211. .RE
  212. .PP
  213. .SH "Author"
  214. .PP
  215. Generated automatically by Doxygen for José from the source code\&.