include/libwebsockets/lws-jwe.h

   1 /*
   2  * libwebsockets - JSON Web Encryption
   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  * JWE Compact Serialization consists of
  24  *
  25  *     BASE64URL(UTF8(JWE Protected Header)) || '.' ||
  26  *     BASE64URL(JWE Encrypted Key)          || '.' ||
  27  *     BASE64URL(JWE Initialization Vector)  || '.' ||
  28  *     BASE64URL(JWE Ciphertext)             || '.' ||
  29  *     BASE64URL(JWE Authentication Tag)
  30  */
  31
  32 #define LWS_JWE_RFC3394_OVERHEAD_BYTES 8
  33 #define LWS_JWE_AES_IV_BYTES 16
  34
  35 #define LWS_JWE_LIMIT_RSA_KEY_BITS 4096
  36 #define LWS_JWE_LIMIT_AES_KEY_BITS (512 + 64) /* RFC3394 Key Wrap adds 64b */
  37 #define LWS_JWE_LIMIT_EC_KEY_BITS  528 /* 521 rounded to byte boundary */
  38 #define LWS_JWE_LIMIT_HASH_BITS    (LWS_GENHASH_LARGEST * 8)
  39
  40 /* the largest key element for any cipher */
  41 #define LWS_JWE_LIMIT_KEY_ELEMENT_BYTES (LWS_JWE_LIMIT_RSA_KEY_BITS / 8)
  42
  43
  44 struct lws_jwe {
  45         struct lws_jose jose;
  46         struct lws_jws jws;
  47         struct lws_jwk jwk;
  48
  49         /*
  50          * We have to keep a copy of the CEK so we can reuse it with later
  51          * key encryptions for the multiple recipient case.
  52          */
  53         uint8_t cek[LWS_JWE_LIMIT_KEY_ELEMENT_BYTES];
  54         unsigned int cek_valid:1;
  55
  56         int recip;
  57 };
  58
  59 LWS_VISIBLE LWS_EXTERN void
  60 lws_jwe_init(struct lws_jwe *jwe, struct lws_context *context);
  61
  62 LWS_VISIBLE LWS_EXTERN void
  63 lws_jwe_destroy(struct lws_jwe *jwe);
  64
  65 LWS_VISIBLE LWS_EXTERN void
  66 lws_jwe_be64(uint64_t c, uint8_t *p8);
  67
  68 /*
  69  * JWE Compact Serialization consists of
  70  *
  71  *     BASE64URL(UTF8(JWE Protected Header)) || '.' ||
  72  *     BASE64URL(JWE Encrypted Key)          || '.' ||
  73  *     BASE64URL(JWE Initialization Vector)  || '.' ||
  74  *     BASE64URL(JWE Ciphertext)             || '.' ||
  75  *     BASE64URL(JWE Authentication Tag)
  76  */
  77
  78 LWS_VISIBLE LWS_EXTERN int
  79 lws_jwe_render_compact(struct lws_jwe *jwe, char *out, size_t out_len);
  80
  81 LWS_VISIBLE int
  82 lws_jwe_render_flattened(struct lws_jwe *jwe, char *out, size_t out_len);
  83
  84 LWS_VISIBLE LWS_EXTERN int
  85 lws_jwe_json_parse(struct lws_jwe *jwe, const uint8_t *buf, int len,
  86                    char *temp, int *temp_len);
  87
  88 /**
  89  * lws_jwe_auth_and_decrypt() - confirm and decrypt JWE
  90  *
  91  * \param jose: jose context
  92  * \param jws: jws / jwe context... .map and .map_b64 must be filled already
  93  *
  94  * This is a high level JWE decrypt api that takes a jws with the maps
  95  * already processed, and if the authentication passes, returns the decrypted
  96  * plaintext in jws.map.buf[LJWE_CTXT] and its length in jws.map.len[LJWE_CTXT].
  97  *
  98  * In the jws, the following fields must have been set by the caller
  99  *
 100  * .context
 101  * .jwk (the key encryption key)
 102  * .map
 103  * .map_b64
 104  *
 105  * Having the b64 and decoded maps filled externally makes it flexible where
 106  * the data was picked from, eg, from a Complete JWE JSON serialization, a
 107  * flattened one, or a Compact Serialization.
 108  *
 109  * Returns decrypt length, or -1 for failure.
 110  */
 111 LWS_VISIBLE LWS_EXTERN int
 112 lws_jwe_auth_and_decrypt(struct lws_jwe *jwe, char *temp, int *temp_len);
 113
 114 /**
 115  * lws_jwe_encrypt() - perform JWE encryption
 116  *
 117  * \param jose: the JOSE header information (encryption types, etc)
 118  * \param jws: the JWE elements, pointer to jwk etc
 119  * \param temp: parent-owned buffer to "allocate" elements into
 120  * \param temp_len: amount of space available in temp
 121  *
 122  * May be called up to LWS_JWS_MAX_RECIPIENTS times to encrypt the same CEK
 123  * multiple ways on the same JWE payload.
 124  *
 125  * returns the amount of temp used, or -1 for error.
 126  */
 127 LWS_VISIBLE LWS_EXTERN int
 128 lws_jwe_encrypt(struct lws_jwe *jwe, char *temp, int *temp_len);
 129
 130 /**
 131  * lws_jwe_create_packet() - add b64 sig to b64 hdr + payload
 132  *
 133  * \param jwe: the struct lws_jwe we are trying to render
 134  * \param payload: unencoded payload JSON
 135  * \param len: length of unencoded payload JSON
 136  * \param nonce: Nonse string to include in protected header
 137  * \param out: buffer to take signed packet
 138  * \param out_len: size of \p out buffer
 139  * \param conext: lws_context to get random from
 140  *
 141  * This creates a "flattened" JWS packet from the jwk and the plaintext
 142  * payload, and signs it.  The packet is written into \p out.
 143  *
 144  * This does the whole packet assembly and signing, calling through to
 145  * lws_jws_sign_from_b64() as part of the process.
 146  *
 147  * Returns the length written to \p out, or -1.
 148  */
 149 LWS_VISIBLE LWS_EXTERN int
 150 lws_jwe_create_packet(struct lws_jwe *jwe,
 151                       const char *payload, size_t len, const char *nonce,
 152                       char *out, size_t out_len, struct lws_context *context);
 153
 154
 155 /* only exposed because we have test vectors that need it */
 156 LWS_VISIBLE LWS_EXTERN int
 157 lws_jwe_auth_and_decrypt_cbc_hs(struct lws_jwe *jwe, uint8_t *enc_cek,
 158                                         uint8_t *aad, int aad_len);
 159
 160 /* only exposed because we have test vectors that need it */
 161 LWS_VISIBLE LWS_EXTERN int
 162 lws_jwa_concat_kdf(struct lws_jwe *jwe, int direct,
 163                    uint8_t *out, const uint8_t *shared_secret, int sslen);