jwe.h 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446
  1. /* vim: set tabstop=8 shiftwidth=4 softtabstop=4 expandtab smarttab colorcolumn=80: */
  2. /*
  3. * Copyright 2016 Red Hat, Inc.
  4. *
  5. * Licensed under the Apache License, Version 2.0 (the "License");
  6. * you may not use this file except in compliance with the License.
  7. * You may obtain a copy of the License at
  8. *
  9. * http://www.apache.org/licenses/LICENSE-2.0
  10. *
  11. * Unless required by applicable law or agreed to in writing, software
  12. * distributed under the License is distributed on an "AS IS" BASIS,
  13. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14. * See the License for the specific language governing permissions and
  15. * limitations under the License.
  16. */
  17. /**
  18. * JSON Web Encryption (RFC 7516)
  19. *
  20. * A JSON Web Encryption (JWE) object contains (usually) two levels of
  21. * encryption. First, the plaintext is encrypted with a random symmetric key.
  22. * In José, we call this key the Content Encryption Key (CEK). Next, the CEK is
  23. * wrapped (encrypted) with one or more keys. These keys are standard JSON Web
  24. * Keys (JWK) and may be symmetric or asymmetric.
  25. *
  26. * Thus there is (usually) one CEK and one or more JWKs. However, there are
  27. * some exceptions to this rule. Two such examples are the algorithms: "dir"
  28. * and "ECDH-ES". In the first case, the JWK is a symmetric key and is used
  29. * directly as the CEK. In the second case, an ECDH key exchange is performed
  30. * and the result is used directly as the CEK. But in general, the maxim holds.
  31. *
  32. * This means that you can encrypt the data using one CEK and then encrypt the
  33. * CEK to multiple recipients. With this schema, multiple recipients can each
  34. * decrypt the data using their own key without having to send separate
  35. * ciphertext to each recipient.
  36. *
  37. * For maximum flexibility, José structures its API to take advantage of this
  38. * schema. For example, when encrypting to two recipients, the code could look
  39. * like this (error handling omitted):
  40. *
  41. * json_t *enc(void *plaintext, size_t len, json_t *jwk0, json_t *jwk1) {
  42. * json_auto_t *jwe = json_object();
  43. * json_auto_t *cek = json_object();
  44. *
  45. * // Wrap to the first recipient (CEK generated implicitly)
  46. * jose_jwe_enc_jwk(NULL, jwe, NULL, jwk0, cek);
  47. *
  48. * // Wrap to the second recipient
  49. * jose_jwe_enc_jwk(NULL, jwe, NULL, jwk1, cek);
  50. *
  51. * // Encrypt plaintext using the generated CEK
  52. * jose_jwe_enc_cek(NULL, jwe, cek, plaintext, len);
  53. *
  54. * return json_incref(jwe);
  55. * }
  56. *
  57. * However, because José intends to be easy to use, we also provide shortcuts.
  58. * For example, you could use a JWKSet which contains multiple JWKs:
  59. *
  60. * json_t *enc(void *plaintext, size_t len, json_t *jwkset) {
  61. * json_auto_t *jwe = json_object();
  62. *
  63. * // Perform wrapping and encryption to all recipients
  64. * jose_jwe_enc(NULL, jwe, NULL, jwkset, plaintext, len);
  65. *
  66. * return json_incref(jwe);
  67. * }
  68. *
  69. * Here are two tips to remember. First, let José generate your CEK implicitly.
  70. * Second, always perform wrapping before encryption. Both of these tips are
  71. * important because some wrapping algorithms may impose constraints on the
  72. * generation of the CEK.
  73. *
  74. * To decrypt a JWE, we just reverse the process. First, we use a JWK to
  75. * unwrap the CEK. Then we use the CEK to decrypt the ciphertext. Here is how
  76. * that might look in code (again, error handling omitted):
  77. *
  78. * void *dec(json_t *jwe, json_t *jwk, size_t *len) {
  79. * json_auto_t *cek = NULL;
  80. *
  81. * // Unwrap the CEK using our JWK
  82. * cek = jose_jwe_dec_jwk(NULL, jwe, NULL, jwk);
  83. *
  84. * // Decrypt ciphertext using the CEK
  85. * return jose_jwe_dec_cek(NULL, jwe, cek, len);
  86. * }
  87. *
  88. * Or, again, in simplified form:
  89. *
  90. * void *dec(json_t *jwe, json_t *jwk, size_t *len) {
  91. * return jose_jwe_dec(NULL, jwe, NULL, jwk, len);
  92. * }
  93. *
  94. * If you need to forward a JWE to a new recipient, you can do this without
  95. * performing re-encryption. Just unwrap the CEK and then wrap the CEK again
  96. * using a new JWK. For example:
  97. *
  98. * void fwd(json_t *jwe, json_t *oldjwk, json_t *newjwk) {
  99. * json_auto_t *cek = NULL;
  100. *
  101. * // Unwrap the CEK using the old JWK
  102. * cek = jose_jwe_dec_jwk(NULL, jwe, NULL, oldjwk);
  103. *
  104. * // Wrap the CEK to the new JWK
  105. * jose_jwe_enc_jwk(NULL, jwe, NULL, newjwk, cek);
  106. * }
  107. *
  108. * In all the above examples, parameters like which encryption algorithms to
  109. * use were inferred from our keys. Where such an inferrence cannot be made,
  110. * sensible and secure defaults were chosen automatically. If you would like
  111. * more control over the process, simply set parameters in the appropriate
  112. * objects (more on this in the function documentation). For example,
  113. * to enable plaintext compression, you can specify the \p zip property
  114. * in the JWE Protected Header:
  115. *
  116. * json_t *enc(void *plaintext, size_t len, json_t *jwkset) {
  117. * json_auto_t *jwe = json_pack("{s:{s:s}}", "protected", "zip", "DEF");
  118. *
  119. * // Perform compressed wrapping and encryption to all recipients
  120. * jose_jwe_enc(NULL, jwe, NULL, jwkset, plaintext, len);
  121. *
  122. * return json_incref(jwe);
  123. * }
  124. *
  125. * José currently supports the "alg", "enc" and "zip" header parameters, as
  126. * well as any algorithm-specific header parameters used by the specific
  127. * algorithms we implement. Other header parameters may be specified, but do
  128. * not effect the behavior of José's JWE implementation.
  129. *
  130. * \defgroup jose_jwe JWE
  131. * \see https://tools.ietf.org/html/rfc7516
  132. * @{
  133. */
  134. #pragma once
  135. #include "cfg.h"
  136. #include "io.h"
  137. #include <jansson.h>
  138. #include <stdbool.h>
  139. #include <stdint.h>
  140. /**
  141. * Merges the JOSE headers of a JWE object and a JWE recpient object.
  142. *
  143. * \param jwe A JWE object.
  144. * \param rcp A JWE recipient object.
  145. * \return The newly allocated JOSE header.
  146. */
  147. json_t *
  148. jose_jwe_hdr(const json_t *jwe, const json_t *rcp);
  149. /**
  150. * Wraps and encrypts plaintext.
  151. *
  152. * This function is a thin wrapper around the jose_jwe_enc_io() function
  153. * allowing the user to specify the plaintext in a single call. The ciphertext
  154. * output will be appended to the JWE as the "ciphertext" property.
  155. *
  156. * \see jose_jwe_enc_cek_io()
  157. * \param cfg The configuration context (optional).
  158. * \param jwe The JWE object.
  159. * \param rcp The JWE recipient object(s) or NULL.
  160. * \param jwk The JWK(s) or JWKSet used for wrapping.
  161. * \param pt The plaintext.
  162. * \param ptl The length of the plaintext.
  163. * \return On success, true. Otherwise, false.
  164. */
  165. bool
  166. jose_jwe_enc(jose_cfg_t *cfg, json_t *jwe, json_t *rcp, const json_t *jwk,
  167. const void *pt, size_t ptl);
  168. /**
  169. * Wraps and encrypts plaintext using streaming.
  170. *
  171. * This function is a thin wrapper around the jose_jwe_enc_jwk() and
  172. * jose_jwe_enc_cek_io() functions, removing the complexity of managing the CEK.
  173. *
  174. * \see jose_jwe_enc_jwk()
  175. * \see jose_jwe_enc_cek_io()
  176. * \param cfg The configuration context (optional).
  177. * \param jwe The JWE object.
  178. * \param rcp The JWE recipient object(s) or NULL.
  179. * \param jwk The JWK(s) or JWKSet used for wrapping.
  180. * \param next The next IO object in the chain.
  181. * \return The new IO object or NULL on error.
  182. */
  183. jose_io_t *
  184. jose_jwe_enc_io(jose_cfg_t *cfg, json_t *jwe, json_t *rcp, const json_t *jwk,
  185. jose_io_t *next);
  186. /**
  187. * Wraps a CEK with a JWK.
  188. *
  189. * The purpose of this function is to wrap (encrypt) or, in some cases, produce
  190. * the CEK (\p cek) from the provided JWK(s) (\p jwk). This function can be
  191. * used in two modes: single-JWK and multi-JWK.
  192. *
  193. * In single-JWK mode, the \p jwk parameter contains a JWK object and the
  194. * \p rcp parameter must contain either a JWE recipient object or NULL, in
  195. * which case a default empty JWE recipient object is created internally.
  196. *
  197. * Multi-JWK mode works exactly the same as single-JWK mode except that it
  198. * performs multiple wrappings in a single call. This mode is enabled by
  199. * passing either an array of JWK objects or a JWKSet as the \p jwk parameter.
  200. * In this mode, the \p rcp parameter contains one of the following values:
  201. *
  202. * 1. A JWE recipient object that will be used for all wrappings. In this case,
  203. * a copy will be made for each wrapping and \p rcp will not be modified in
  204. * any way.
  205. *
  206. * 2. An array of JWE recipient objects. Each object will be used with its
  207. * corresponding JWK from \p jwk. If the arrays in \p sig and \p jwk are a
  208. * different size, an error will occur.
  209. *
  210. * 3. NULL. This has the same effect as passing NULL for each separate JWK.
  211. *
  212. * In either mode, if the resulting JWE (\p jwe) would contain only a single
  213. * recipient, the JWE will be represented in Flattened JWE JSON Serialization
  214. * Syntax. Otherwise, it will be represented in General JWE JSON Serialization
  215. * Syntax.
  216. *
  217. * If the "alg" parameter is not specified in the JOSE Header, it will be
  218. * inferred from the JWK and the chosen algorithm will be added to the JWE
  219. * Per-Recipient Unprotected Header. Likewise, any missing, required,
  220. * algorithm-specific parameters will be either inferred or sensible, secure
  221. * defaults will be chosen and the results will be added to the JWE
  222. * Per-Recipient Unprotected Header.
  223. *
  224. * If the provided CEK (\p cek) does not contain key material, it will be
  225. * implicitly generated during the first call to jose_jwe_enc_jwk(). This
  226. * important feature enables the use of the "dir" and "ECDH-ES" algorithms.
  227. * In the case of the "dir" algorithm, the JWK is the CEK and thus the key
  228. * material is copied from \p jwk to \p cek. A similar situation arises with
  229. * the algorithm "ECDH-ES" where the result of a key exchange is used as the
  230. * CEK; thus, the CEK is produced during the wrapping process. This feature
  231. * implies that if multiple wrappings are created, only one of them may have
  232. * the algorithm "ECDH-ES" and it must be the first wrapping. Attempting to
  233. * use "ECDH-ES" with an existing CEK will result in an error.
  234. *
  235. * It is additionally possible to pass a password JSON string as key input
  236. * to the PBES2 family of algorithms anywhere a JWK can be used. Likewise, if
  237. * the "alg" JOSE Header parameter is not specified and a JSON string is used
  238. * in place of a JWK, the PBES2 family of algorithms will be inferred.
  239. *
  240. * \param cfg The configuration context (optional).
  241. * \param jwe The JWE object.
  242. * \param rcp The JWE recipient object(s) or NULL.
  243. * \param jwk The JWK(s) or JWKSet used for wrapping.
  244. * \param cek The CEK to wrap (if empty, generated).
  245. * \return On success, true. Otherwise, false.
  246. */
  247. bool
  248. jose_jwe_enc_jwk(jose_cfg_t *cfg, json_t *jwe, json_t *rcp, const json_t *jwk,
  249. json_t *cek);
  250. /**
  251. * Encrypts plaintext with the CEK.
  252. *
  253. * This function is a thin wrapper around the jose_jwe_enc_cek_io() function
  254. * allowing the user to specify the plaintext in a single call. The ciphertext
  255. * output will be appended to the JWE as the "ciphertext" property.
  256. *
  257. * \see jose_jwe_enc_cek_io()
  258. * \param cfg The configuration context (optional).
  259. * \param jwe The JWE object.
  260. * \param cek The CEK object.
  261. * \param pt The plaintext.
  262. * \param ptl The length of the plaintext.
  263. * \return On success, true. Otherwise, false.
  264. */
  265. bool
  266. jose_jwe_enc_cek(jose_cfg_t *cfg, json_t *jwe, const json_t *cek,
  267. const void *pt, size_t ptl);
  268. /**
  269. * Encrypts plaintext with the CEK using streaming.
  270. *
  271. * The plaintext is provided through the returned IO object. The plaintext
  272. * will be encrypted and written to the \p next IO object. This IO object
  273. * works on binary data, so you may need to use a URL-safe Base64 decoder on
  274. * input and a URL-safe Base64 encoder on output, depending on your situation.
  275. *
  276. * Compressed plaintext can be implicitly enabled by specifying the "zip"
  277. * parameter the JWE Protected Header.
  278. *
  279. * If the JWE Protected Header is a JSON object rather than an encoded string,
  280. * this function will encode the JWE Protected Header to its URL-safe Base64
  281. * encoding as defined in RFC 7516. However, this function will never modify
  282. * a JWE Protected Header that is already encoded.
  283. *
  284. * If the "enc" parameter is not specified in the JWE Protected Header or the
  285. * JWE Shared Unprotected Header, it will be inferred from the CEK and stored
  286. * in either the JWE Protected Header or the JWE Shared Unprotected Header
  287. * (preferring the JWE Protected header if it can be modified).
  288. *
  289. * Please note that the "tag" property will only be added to the JWE when
  290. * \ref jose_io_t.done() returns.
  291. *
  292. * \param cfg The configuration context (optional).
  293. * \param jwe The JWE object.
  294. * \param cek The CEK object.
  295. * \param next The next IO object in the chain.
  296. * \return The new IO object or NULL on error.
  297. */
  298. jose_io_t *
  299. jose_jwe_enc_cek_io(jose_cfg_t *cfg, json_t *jwe, const json_t *cek,
  300. jose_io_t *next);
  301. /**
  302. * Unwraps and decrypts ciphertext.
  303. *
  304. * This function is a thin wrapper around the jose_jwe_dec_io() function
  305. * allowing the user to obtain the plaintext in a single call. The ciphertext
  306. * input will be obtained from the JWE "ciphertext" property.
  307. *
  308. * \see jose_jwe_dec_io()
  309. * \param cfg The configuration context (optional).
  310. * \param jwe The JWE object.
  311. * \param rcp The JWE recipient object(s) or NULL.
  312. * \param jwk The JWK(s) or JWKSet used for wrapping.
  313. * \param ptl The length of the plaintext (output).
  314. * \return The newly-allocated plaintext.
  315. */
  316. void *
  317. jose_jwe_dec(jose_cfg_t *cfg, const json_t *jwe, const json_t *rcp,
  318. const json_t *jwk, size_t *ptl);
  319. /**
  320. * Unwraps and decrypts ciphertext using streaming.
  321. *
  322. * This function is a thin wrapper around the jose_jwe_dec_jwk() and
  323. * jose_jwe_dec_cek_io() functions, removing the complexity of managing the CEK.
  324. *
  325. * \see jose_jwe_dec_jwk()
  326. * \see jose_jwe_dec_cek_io()
  327. * \param cfg The configuration context (optional).
  328. * \param jwe The JWE object.
  329. * \param rcp The JWE recipient object(s) or NULL.
  330. * \param jwk The JWK(s) or JWKSet used for unwrapping.
  331. * \param next The next IO object in the chain.
  332. * \return The new IO object or NULL on error.
  333. */
  334. jose_io_t *
  335. jose_jwe_dec_io(jose_cfg_t *cfg, const json_t *jwe, const json_t *rcp,
  336. const json_t *jwk, jose_io_t *next);
  337. /**
  338. * Unwraps a CEK with a JWK.
  339. *
  340. * The purpose of this function is to unwrap (decrypt) or, in some cases,
  341. * produce the CEK (\p cek) from the provided JWK(s) (\p jwk). This function
  342. * can be used in two modes: single-JWK and multi-JWK.
  343. *
  344. * In single-JWK mode, the \p jwk parameter contains a JWK object and the
  345. * \p rcp parameter must contain either a JWE recipient object you wish to
  346. * unwrap or NULL, in which case all JWE recipients will be tried.
  347. *
  348. * Multi-JWK mode works exactly the same as single-JWK mode except that it
  349. * attempts to unwrap with multiple JWKs in a single call. This mode is enabled
  350. * by passing either an array of JWK objects or a JWKSet as the \p jwk
  351. * parameter. In this mode, the \p rcp parameter contains one of the following
  352. * values:
  353. *
  354. * 1. A JWE recipient object that will be used for all attempted unwrappings.
  355. *
  356. * 2. An array of JWE recipient objects. Each object will be used with its
  357. * corresponding JWK from \p jwk. If the arrays in \p sig and \p jwk are a
  358. * different size, an error will occur.
  359. *
  360. * 3. NULL. This has the same effect as passing NULL for each separate JWK.
  361. *
  362. * In either mode, a CEK is returned for the first JWK that successfully
  363. * unwraps a CEK. Two exceptions to this rule are if the "dir" or "ECDH-ES"
  364. * algorithms are used. In this case, a CEK may be returned which will fail
  365. * during decryption since there is no way to completely validate the JWK with
  366. * these algorithms. Thus, we suggest placing the keys for these algorithms
  367. * last when unwrapping with multiple JWKs.
  368. *
  369. * If the "alg" parameter is not specified in the JOSE Header, it will be
  370. * inferred from the JWK. This includes using a JSON string in place of a JWK
  371. * for the PBES2 family of algorithms.
  372. *
  373. * \param cfg The configuration context (optional).
  374. * \param jwe The JWE object.
  375. * \param rcp The JWE recipient object(s) or NULL.
  376. * \param jwk The JWK(s) or JWKSet used for wrapping.
  377. * \return On success, a newly-allocated CEK object. Otherwise, NULL.
  378. */
  379. json_t *
  380. jose_jwe_dec_jwk(jose_cfg_t *cfg, const json_t *jwe, const json_t *rcp,
  381. const json_t *jwk);
  382. /**
  383. * Decrypts ciphertext with the CEK.
  384. *
  385. * This function is a thin wrapper around the jose_jwe_dec_cek_io() function
  386. * allowing the user to obtain the plaintext in a single call. The ciphertext
  387. * input will be obtained from the JWE "ciphertext" property.
  388. *
  389. * \see jose_jwe_dec_cek_io()
  390. * \param cfg The configuration context (optional).
  391. * \param jwe The JWE object.
  392. * \param cek The CEK object.
  393. * \param ptl The length of the plaintext (output).
  394. * \return The newly-allocated plaintext.
  395. */
  396. void *
  397. jose_jwe_dec_cek(jose_cfg_t *cfg, const json_t *jwe, const json_t *cek,
  398. size_t *ptl);
  399. /**
  400. * Decrypts ciphertext with the CEK using streaming.
  401. *
  402. * The ciphertext is provided through the returned IO object. The ciphertext
  403. * will be decrypted and written to the \p next IO object. This IO object
  404. * works on binary data, so you may need to use a URL-safe Base64 decoder on
  405. * input and a URL-safe Base64 encoder on output, depending on your situation.
  406. *
  407. * Please note that validation of the ciphertext integrity protection is delayed
  408. * until \ref jose_io_t.done() returns. This means it is incredibly important
  409. * to check this return value and it is also important to be careful with the
  410. * plaintext emitted until this check is performed.
  411. *
  412. * Compressed plaintext will be internally decompressed if the "zip" property
  413. * is appropriately defined.
  414. *
  415. * If the "enc" parameter is not specified in the JWE Protected Header or the
  416. * JWE Shared Unprotected Header, it will be inferred from the CEK.
  417. *
  418. * Please note that the "tag" property on the JWE will only be accessed when
  419. * \ref jose_io_t.done() is called. So you may define it at any time on the
  420. * JWE object before calling \ref jose_io_t.done().
  421. *
  422. * \param cfg The configuration context (optional).
  423. * \param jwe The JWE object.
  424. * \param cek The CEK object.
  425. * \param next The next IO object in the chain.
  426. * \return The new IO object or NULL on error.
  427. */
  428. jose_io_t *
  429. jose_jwe_dec_cek_io(jose_cfg_t *cfg, const json_t *jwe, const json_t *cek,
  430. jose_io_t *next);
  431. /** @} */