include/libwebsockets/lws-jwk.h

   1 /*
   2  * libwebsockets - small server side websockets and web server implementation
   3  *
   4  * Copyright (C) 2010 - 2018 Andy Green <andy@warmcat.com>
   5  *
   6  *  This library is free software; you can redistribute it and/or
   7  *  modify it under the terms of the GNU Lesser General Public
   8  *  License as published by the Free Software Foundation:
   9  *  version 2.1 of the License.
  10  *
  11  *  This library is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  *  Lesser General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU Lesser General Public
  17  *  License along with this library; if not, write to the Free Software
  18  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  19  *  MA  02110-1301  USA
  20  *
  21  * included from libwebsockets.h
  22  */
  23
  24 /*! \defgroup jwk JSON Web Keys
  25  * ## JSON Web Keys API
  26  *
  27  * Lws provides an API to parse JSON Web Keys into a struct lws_gencrypto_keyelem.
  28  *
  29  * "oct" and "RSA" type keys are supported.  For "oct" keys, they are held in
  30  * the "e" member of the struct lws_gencrypto_keyelem.
  31  *
  32  * Keys elements are allocated on the heap.  You must destroy the allocations
  33  * in the struct lws_gencrypto_keyelem by calling
  34  * lws_genrsa_destroy_elements() when you are finished with it.
  35  */
  36 ///@{
  37
  38 enum enum_jwk_meta_tok {
  39         JWK_META_KTY,
  40         JWK_META_KID,
  41         JWK_META_USE,
  42         JWK_META_KEY_OPS,
  43         JWK_META_X5C,
  44         JWK_META_ALG,
  45
  46         LWS_COUNT_JWK_ELEMENTS
  47 };
  48
  49 struct lws_jwk {
  50         /* key data elements */
  51         struct lws_gencrypto_keyelem e[LWS_GENCRYPTO_MAX_KEYEL_COUNT];
  52         /* generic meta key elements, like KID */
  53         struct lws_gencrypto_keyelem meta[LWS_COUNT_JWK_ELEMENTS];
  54         int kty;                        /**< one of LWS_JWK_ */
  55         char private_key; /* nonzero = has private key elements */
  56 };
  57
  58 typedef int (*lws_jwk_key_import_callback)(struct lws_jwk *s, void *user);
  59
  60 struct lws_jwk_parse_state {
  61         struct lws_jwk *jwk;
  62         char b64[(((8192 / 8) * 4) / 3) + 1]; /* enough for 8Kb key */
  63         lws_jwk_key_import_callback per_key_cb;
  64         void *user;
  65         int pos;
  66         unsigned short possible;
  67 };
  68
  69 /** lws_jwk_import() - Create a JSON Web key from the textual representation
  70  *
  71  * \param jwk: the JWK object to create
  72  * \param cb: callback for each jwk-processed key, or NULL if importing a single
  73  *            key with no parent "keys" JSON
  74  * \param user: pointer to be passed to the callback, otherwise ignored by lws.
  75  *              NULL if importing a single key with no parent "keys" JSON
  76  * \param in: a single JWK JSON stanza in utf-8
  77  * \param len: the length of the JWK JSON stanza in bytes
  78  *
  79  * Creates an lws_jwk struct filled with data from the JSON representation.
  80  *
  81  * There are two ways to use this... with some protocols a single jwk is
  82  * delivered with no parent "keys": [] array.  If you call this with cb and
  83  * user as NULL, then the input will be interpreted like that and the results
  84  * placed in s.
  85  *
  86  * The second case is that you are dealing with a "keys":[] array with one or
  87  * more keys in it.  In this case, the function iterates through the keys using
  88  * s as a temporary jwk, and calls the user-provided callback for each key in
  89  * turn while it return 0 (nonzero return from the callback terminates the
  90  * iteration through any further keys).
  91  */
  92 LWS_VISIBLE LWS_EXTERN int
  93 lws_jwk_import(struct lws_jwk *jwk, lws_jwk_key_import_callback cb, void *user,
  94                const char *in, size_t len);
  95
  96 /** lws_jwk_destroy() - Destroy a JSON Web key
  97  *
  98  * \param jwk: the JWK object to destroy
  99  *
 100  * All allocations in the lws_jwk are destroyed
 101  */
 102 LWS_VISIBLE LWS_EXTERN void
 103 lws_jwk_destroy(struct lws_jwk *jwk);
 104
 105 /** lws_jwk_dup_oct() - Set a jwk to a dup'd binary OCT key
 106  *
 107  * \param jwk: the JWK object to set
 108  * \param key: the JWK object to destroy
 109  * \param len: the JWK object to destroy
 110  *
 111  * Sets the kty to OCT, allocates len bytes for K and copies len bytes of key
 112  * into the allocation.
 113  */
 114 LWS_VISIBLE LWS_EXTERN int
 115 lws_jwk_dup_oct(struct lws_jwk *jwk, const void *key, int len);
 116
 117 /** lws_jwk_export() - Export a JSON Web key to a textual representation
 118  *
 119  * \param jwk: the JWK object to export
 120  * \param _private: 0 = just export public parts, 1 = export everything
 121  * \param p: the buffer to write the exported JWK to
 122  * \param len: the length of the buffer \p p in bytes... reduced by used amount
 123  *
 124  * Returns length of the used part of the buffer if OK, or -1 for error.
 125  *
 126  * Serializes the content of the JWK into a char buffer.
 127  */
 128 LWS_VISIBLE LWS_EXTERN int
 129 lws_jwk_export(struct lws_jwk *jwk, int _private, char *p, int *len);
 130
 131 /** lws_jwk_load() - Import a JSON Web key from a file
 132  *
 133  * \param jwk: the JWK object to load into
 134  * \param filename: filename to load from
 135  *
 136  * Returns 0 for OK or -1 for failure
 137  *
 138  * There are two ways to use this... with some protocols a single jwk is
 139  * delivered with no parent "keys": [] array.  If you call this with cb and
 140  * user as NULL, then the input will be interpreted like that and the results
 141  * placed in s.
 142  *
 143  * The second case is that you are dealing with a "keys":[] array with one or
 144  * more keys in it.  In this case, the function iterates through the keys using
 145  * s as a temporary jwk, and calls the user-provided callback for each key in
 146  * turn while it return 0 (nonzero return from the callback terminates the
 147  * iteration through any further keys, leaving the last one in s).
 148  */
 149 LWS_VISIBLE LWS_EXTERN int
 150 lws_jwk_load(struct lws_jwk *jwk, const char *filename,
 151              lws_jwk_key_import_callback cb, void *user);
 152
 153 /** lws_jwk_save() - Export a JSON Web key to a file
 154  *
 155  * \param jwk: the JWK object to save from
 156  * \param filename: filename to save to
 157  *
 158  * Returns 0 for OK or -1 for failure
 159  */
 160 LWS_VISIBLE LWS_EXTERN int
 161 lws_jwk_save(struct lws_jwk *jwk, const char *filename);
 162
 163 /** lws_jwk_rfc7638_fingerprint() - jwk to RFC7638 compliant fingerprint
 164  *
 165  * \param jwk: the JWK object to fingerprint
 166  * \param digest32: buffer to take 32-byte digest
 167  *
 168  * Returns 0 for OK or -1 for failure
 169  */
 170 LWS_VISIBLE LWS_EXTERN int
 171 lws_jwk_rfc7638_fingerprint(struct lws_jwk *jwk, char *digest32);
 172
 173 /** lws_jwk_strdup_meta() - allocate a duplicated string meta element
 174  *
 175  * \param jwk: the JWK object to fingerprint
 176  * \param idx: JWK_META_ element index
 177  * \param in: string to copy
 178  * \param len: length of string to copy
 179  *
 180  * Returns 0 for OK or -1 for failure
 181  */
 182 LWS_VISIBLE LWS_EXTERN int
 183 lws_jwk_strdup_meta(struct lws_jwk *jwk, enum enum_jwk_meta_tok idx,
 184                     const char *in, int len);
 185
 186
 187 LWS_VISIBLE LWS_EXTERN int
 188 lws_jwk_dump(struct lws_jwk *jwk);
 189
 190 /** lws_jwk_generate() - create a new key of given type and characteristics
 191  *
 192  * \param context: the struct lws_context used for RNG
 193  * \param jwk: the JWK object to fingerprint
 194  * \param kty: One of the LWS_GENCRYPTO_KTY_ key types
 195  * \param bits: for OCT and RSA keys, the number of bits
 196  * \param curve: for EC keys, the name of the curve
 197  *
 198  * Returns 0 for OK or -1 for failure
 199  */
 200 LWS_VISIBLE int
 201 lws_jwk_generate(struct lws_context *context, struct lws_jwk *jwk,
 202                  enum lws_gencrypto_kty kty, int bits, const char *curve);
 203
 204 ///@}