jwk.h 7.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198
  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 Keys (RFC 7517)
  19. *
  20. * A JSON Web Key (JWS) is a standard data format for expresing cryptographic
  21. * keys in JSON.
  22. *
  23. * \defgroup jose_jwk JWK
  24. * \see https://tools.ietf.org/html/rfc7517
  25. * \see https://tools.ietf.org/html/rfc7638
  26. * @{
  27. */
  28. #pragma once
  29. #include "cfg.h"
  30. #include <jansson.h>
  31. #include <stdbool.h>
  32. #include <stdint.h>
  33. /**
  34. * Generates a new JWK.
  35. *
  36. * The JWK is generated using hints from the input in exactly the same format
  37. * as you would find in the output. For example, the most common way to
  38. * generate a key is to specify the algorithm you'd like to use the key with.
  39. * For example (error handling omitted):
  40. *
  41. * json_t *gen(void) {
  42. * json_auto_t *jwk = json_pack("{s:s}", "alg", "ES256");
  43. * jose_jwk_gen(NULL, jwk);
  44. * return json_incref(jwk);
  45. * }
  46. *
  47. * This method is preferred because other metadata can be inferred from the
  48. * algorithm name, such as the key usage. Additionally, the algorithm metadata
  49. * can be used to automatically generate correct headers when creating
  50. * signatures (JWS) or encryptions (JWE). Thus, you should always default to
  51. * creating keys by their algorithm usage.
  52. *
  53. * However, should your requirements differ, you can also generate a key using
  54. * raw parameters (again, error handling omitted):
  55. *
  56. * json_t *gen(void) {
  57. * json_auto_t *jwk = json_pack("{s:s,s:s}", "kty", "EC", "crv", "P-256");
  58. * jose_jwk_gen(NULL, jwk);
  59. * return json_incref(jwk);
  60. * }
  61. *
  62. * json_t *gen(void) {
  63. * json_auto_t *jwk = json_pack("{s:s,s:i}", "kty", "RSA", "bits", 2048);
  64. * jose_jwk_gen(NULL, jwk);
  65. * return json_incref(jwk);
  66. * }
  67. *
  68. * json_t *gen(void) {
  69. * json_auto_t *jwk = json_pack("{s:s,s:i}", "kty", "oct", "bytes", 32);
  70. * jose_jwk_gen(NULL, jwk);
  71. * return json_incref(jwk);
  72. * }
  73. *
  74. * In this case, "bits" and "bytes" will be removed from the final output.
  75. *
  76. * \see https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms
  77. * \param cfg The configuration context (optional).
  78. * \param jwk The JWK to generate.
  79. * \return On success, true. Otherwise, false.
  80. */
  81. bool
  82. jose_jwk_gen(jose_cfg_t *cfg, json_t *jwk);
  83. /**
  84. * Removes all private key material from a JWK.
  85. *
  86. * In addition, this function will remove any key operations from the
  87. * \p key_ops JWK property (if present) that apply only to the private key.
  88. *
  89. * This function should be used before exporting keys to third parties.
  90. *
  91. * \param cfg The configuration context (optional).
  92. * \param jwk The JWK to remove private keys from.
  93. * \return On success, true. Otherwise, false.
  94. */
  95. bool
  96. jose_jwk_pub(jose_cfg_t *cfg, json_t *jwk);
  97. /**
  98. * Determines if an operation is permitted for a JWK.
  99. *
  100. * The operation to be confirmed (\p op) is always specified according to
  101. * the syntax of the "key_ops" JWK property, even when the "use" property
  102. * is defined on the JWK.
  103. *
  104. * This function has two modes of operation. If \p req is false, then JWKs
  105. * which do not have any key use metadata will be approved for this operation.
  106. * However, if \p req is true then this metadata will be required for approval.
  107. *
  108. * \param cfg The configuration context (optional).
  109. * \param jwk The JWK from which to remove private keys.
  110. * \param req Whether JWK key use metadata is required or not.
  111. * \param op The opperation to seek approval for.
  112. * \return When the JWK is approved, true. Otherwise, false.
  113. */
  114. bool
  115. jose_jwk_prm(jose_cfg_t *cfg, const json_t *jwk, bool req, const char *op);
  116. /**
  117. * Determines whether two JWKs have equal key material.
  118. *
  119. * This function considers relevant the same properties used for generation of
  120. * a thumbprint as defined by RFC 7638.
  121. *
  122. * \see jose_jwk_thp()
  123. * \see jose_jwk_thp_buf()
  124. * \param cfg The configuration context (optional).
  125. * \param a The first JWK to consider.
  126. * \param b The second JWK to consider.
  127. * \return When the two JWKs are equal, true. Otherwise, false.
  128. */
  129. bool
  130. jose_jwk_eql(jose_cfg_t *cfg, const json_t *a, const json_t *b);
  131. /**
  132. * Calculates the thumbprint of a JWK as a URL-safe Base64 encoded JSON string.
  133. *
  134. * This function is a thin wrapper around jose_jwk_thp_buf().
  135. *
  136. * \see jose_jwk_thp_buf()
  137. * \param cfg The configuration context (optional).
  138. * \param jwk The JWK to calculate the thumbprint for.
  139. * \param alg The hash algorithm to use.
  140. * \return On success, a newly-allocated JSON string. Otherwise, NULL.
  141. */
  142. json_t *
  143. jose_jwk_thp(jose_cfg_t *cfg, const json_t *jwk, const char *alg);
  144. /**
  145. * Calculates the thumbprint of a JWK.
  146. *
  147. * This function calculates the thumbprint of a JWK according to the method
  148. * defined by RFC 7638.
  149. *
  150. * If \p thp is NULL, this function returns the size of the buffer required
  151. * for the thumbprint output.
  152. *
  153. * \see https://tools.ietf.org/html/rfc7638
  154. * \param cfg The configuration context (optional).
  155. * \param jwk The JWK to calculate the thumbprint for.
  156. * \param alg The hash algorithm to use.
  157. * \param thp The output hash buffer.
  158. * \param len The size of the output hash buffer.
  159. * \return On success, the number of bytes written. Otherwise, SIZE_MAX.
  160. */
  161. size_t
  162. jose_jwk_thp_buf(jose_cfg_t *cfg, const json_t *jwk,
  163. const char *alg, uint8_t *thp, size_t len);
  164. /**
  165. * Perform a key exchange.
  166. *
  167. * The algorithm for the exchange is inferred from the inputs.
  168. *
  169. * The ECDH algorithm performs a standard elliptic curve multiplication such
  170. * that the public value of \p rem is multiplied by the private value of \p.
  171. *
  172. * The ECMR algorithm has three modes of operation. Where \p lcl has a
  173. * private key (the "d" property), it performs exactly like ECDH. If \p lcl
  174. * does not have a private key and \p rem does have a private key, elliptic
  175. * curve addition is performed. Otherwise, if neither \p lcl nor \p rem have a
  176. * private key, \p rem is subtracted from \p lcl using elliptic curve
  177. * subtraction. When using ECMR, be sure to validate the content of your inputs
  178. * to avoid triggering the incorrect operation!
  179. *
  180. * \param cfg The configuration context (optional).
  181. * \param lcl The local JWK (usually public/private key pair).
  182. * \param rem The remote JWK (usually just a public key).
  183. * \return On success, the JWK result of the key exchange. Otherwise, NULL.
  184. */
  185. json_t *
  186. jose_jwk_exc(jose_cfg_t *cfg, const json_t *lcl, const json_t *rem);
  187. /** @} */