libwebsockets
Lightweight C library for HTML5 websockets
lws-jose.h
Go to the documentation of this file.
1/*
2 * libwebsockets - small server side websockets and web server implementation
3 *
4 * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to
8 * deal in the Software without restriction, including without limitation the
9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10 * sell copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22 * IN THE SOFTWARE.
23 */
24
26 LJJHI_ALG, /* REQUIRED */
27 LJJHI_JKU, /* Optional: string */
28 LJJHI_JWK, /* Optional: jwk JSON object: public key: */
29 LJJHI_KID, /* Optional: string */
30 LJJHI_X5U, /* Optional: string: url of public key cert / chain */
31 LJJHI_X5C, /* Optional: base64 (NOT -url): actual cert */
32 LJJHI_X5T, /* Optional: base64url: SHA-1 of actual cert */
33 LJJHI_X5T_S256, /* Optional: base64url: SHA-256 of actual cert */
34 LJJHI_TYP, /* Optional: string: media type */
35 LJJHI_CTY, /* Optional: string: content media type */
36 LJJHI_CRIT, /* Optional for send, REQUIRED: array of strings:
37 * mustn't contain standardized strings or null set */
38
43
44 LJJHI_ENC, /* JWE only: Optional: string */
45 LJJHI_ZIP, /* JWE only: Optional: string ("DEF" = deflate) */
46
47 LJJHI_EPK, /* Additional arg for JWE ECDH: ephemeral public key */
48 LJJHI_APU, /* Additional arg for JWE ECDH: base64url */
49 LJJHI_APV, /* Additional arg for JWE ECDH: base64url */
50 LJJHI_IV, /* Additional arg for JWE AES: base64url */
51 LJJHI_TAG, /* Additional arg for JWE AES: base64url */
52 LJJHI_P2S, /* Additional arg for JWE PBES2: base64url: salt */
53 LJJHI_P2C, /* Additional arg for JWE PBES2: integer: count */
54
56};
57
60
64
67
74 LWS_JOSE_ENCTYPE_AES_XTS, /* care: requires double-length key */
76};
77
78/* there's a table of these defined in lws-gencrypto-common.c */
79
83 enum lws_jose_algtype algtype_signing; /* the signing cipher */
84 enum lws_jose_algtype algtype_crypto; /* the encryption cipher */
85 const char *alg; /* the JWA enc alg name, eg "ES512" */
86 const char *curve_name; /* NULL, or, eg, "P-256" */
87 unsigned short keybits_min, keybits_fixed;
88 unsigned short ivbits;
89};
90
91/*
92 * For JWS, "JOSE header" is defined to be the union of...
93 *
94 * o JWS Protected Header
95 * o JWS Unprotected Header
96 *
97 * For JWE, the "JOSE header" is the union of...
98 *
99 * o JWE Protected Header
100 * o JWE Shared Unprotected Header
101 * o JWE Per-Recipient Unprotected Header
102 */
103
104#define LWS_JWS_MAX_RECIPIENTS 3
105
107 /*
108 * JOSE per-recipient unprotected header... for JWS this contains
109 * protected / header / signature
110 */
112 struct lws_jwk jwk_ephemeral; /* recipient ephemeral key if any */
113 struct lws_jwk jwk; /* recipient "jwk" key if any */
114};
115
116struct lws_jose {
117 /* JOSE protected and unprotected header elements */
119
121
122 char typ[32];
124
125 /* information from the protected header part */
126 const struct lws_jose_jwe_alg *alg;
128
129 int recipients; /* count of used recipient[] entries */
130};
131
132/**
133 * lws_jose_init() - prepare a struct lws_jose for use
134 *
135 * \param jose: the jose header struct to prepare
136 */
137LWS_VISIBLE LWS_EXTERN void
139
140/**
141 * lws_jose_destroy() - retire a struct lws_jose from use
142 *
143 * \param jose: the jose header struct to destroy
144 */
145LWS_VISIBLE LWS_EXTERN void
147
148/**
149 * lws_gencrypto_jws_alg_to_definition() - look up a jws alg name
150 *
151 * \param alg: the jws alg name
152 * \param jose: pointer to the pointer to the info struct to set on success
153 *
154 * Returns 0 if *jose set, else nonzero for failure
155 */
156LWS_VISIBLE LWS_EXTERN int
158 const struct lws_jose_jwe_alg **jose);
159
160/**
161 * lws_gencrypto_jwe_alg_to_definition() - look up a jwe alg name
162 *
163 * \param alg: the jwe alg name
164 * \param jose: pointer to the pointer to the info struct to set on success
165 *
166 * Returns 0 if *jose set, else nonzero for failure
167 */
168LWS_VISIBLE LWS_EXTERN int
170 const struct lws_jose_jwe_alg **jose);
171
172/**
173 * lws_gencrypto_jwe_enc_to_definition() - look up a jwe enc name
174 *
175 * \param alg: the jwe enc name
176 * \param jose: pointer to the pointer to the info struct to set on success
177 *
178 * Returns 0 if *jose set, else nonzero for failure
179 */
180LWS_VISIBLE LWS_EXTERN int
182 const struct lws_jose_jwe_alg **jose);
183
184/**
185 * lws_jws_parse_jose() - parse a JWS JOSE header
186 *
187 * \param jose: the jose struct to set to parsing results
188 * \param buf: the raw JOSE header
189 * \param len: the length of the raw JOSE header
190 * \param temp: parent-owned buffer to "allocate" elements into
191 * \param temp_len: amount of space available in temp
192 *
193 * returns 0 for success, or -1 for error
194 * *\p temp_len is updated to reflect the amount of \p temp used if successful.
195 */
196LWS_VISIBLE LWS_EXTERN int
198 const char *buf, int len, char *temp, int *temp_len);
199
200/**
201 * lws_jwe_parse_jose() - parse a JWE JOSE header
202 *
203 * \param jose: the jose struct to set to parsing results
204 * \param buf: the raw JOSE header
205 * \param len: the length of the raw JOSE header
206 * \param temp: parent-owned buffer to "allocate" elements into
207 * \param temp_len: amount of space available in temp
208 *
209 * returns 0 for success, or -1 for error
210 * *\p temp_len is updated to reflect the amount of \p temp used if successful.
211 */
212LWS_VISIBLE LWS_EXTERN int
214 const char *buf, int len, char *temp, int *temp_len);
lws_genhash_types
Definition: lws-genhash.h:36
lws_genhmac_types
Definition: lws-genhash.h:45
LWS_VISIBLE LWS_EXTERN int lws_gencrypto_jws_alg_to_definition(const char *alg, const struct lws_jose_jwe_alg **jose)
int recipients
Definition: lws-jose.h:129
unsigned short keybits_fixed
Definition: lws-jose.h:87
const char * curve_name
Definition: lws-jose.h:86
const struct lws_jose_jwe_alg * enc_alg
Definition: lws-jose.h:127
LWS_VISIBLE LWS_EXTERN void lws_jose_init(struct lws_jose *jose)
enum lws_genhmac_types hmac_type
Definition: lws-jose.h:82
lws_jws_jose_hdr_indexes
Definition: lws-jose.h:25
@ LJJHI_X5T
Definition: lws-jose.h:32
@ LJJHI_P2S
Definition: lws-jose.h:52
@ LJJHI_X5U
Definition: lws-jose.h:30
@ LJJHI_TAG
Definition: lws-jose.h:51
@ LWS_COUNT_JOSE_HDR_ELEMENTS
Definition: lws-jose.h:55
@ LJJHI_TYP
Definition: lws-jose.h:34
@ LJJHI_ZIP
Definition: lws-jose.h:45
@ LJJHI_RECIPS_HDR
Definition: lws-jose.h:39
@ LJJHI_CTY
Definition: lws-jose.h:35
@ LJJHI_JKU
Definition: lws-jose.h:27
@ LJJHI_P2C
Definition: lws-jose.h:53
@ LJJHI_RECIPS_HDR_ALG
Definition: lws-jose.h:40
@ LJJHI_APU
Definition: lws-jose.h:48
@ LJJHI_RECIPS_HDR_KID
Definition: lws-jose.h:41
@ LJJHI_APV
Definition: lws-jose.h:49
@ LJJHI_RECIPS_EKEY
Definition: lws-jose.h:42
@ LJJHI_ALG
Definition: lws-jose.h:26
@ LJJHI_KID
Definition: lws-jose.h:29
@ LJJHI_CRIT
Definition: lws-jose.h:36
@ LJJHI_X5C
Definition: lws-jose.h:31
@ LJJHI_X5T_S256
Definition: lws-jose.h:33
@ LJJHI_IV
Definition: lws-jose.h:50
@ LJJHI_EPK
Definition: lws-jose.h:47
@ LJJHI_JWK
Definition: lws-jose.h:28
@ LJJHI_ENC
Definition: lws-jose.h:44
LWS_VISIBLE LWS_EXTERN void lws_jose_destroy(struct lws_jose *jose)
LWS_VISIBLE LWS_EXTERN int lws_gencrypto_jwe_alg_to_definition(const char *alg, const struct lws_jose_jwe_alg **jose)
enum lws_jose_algtype algtype_crypto
Definition: lws-jose.h:84
const struct lws_jose_jwe_alg * alg
Definition: lws-jose.h:126
#define LWS_JWS_MAX_RECIPIENTS
Definition: lws-jose.h:104
struct lws_jwk jwk
Definition: lws-jose.h:113
struct lws_jwk jwk_ephemeral
Definition: lws-jose.h:112
LWS_VISIBLE LWS_EXTERN int lws_jwe_parse_jose(struct lws_jose *jose, const char *buf, int len, char *temp, int *temp_len)
lws_jose_algtype
Definition: lws-jose.h:58
@ LWS_JOSE_ENCTYPE_AES_CFB128
Definition: lws-jose.h:69
@ LWS_JOSE_ENCTYPE_AES_CTR
Definition: lws-jose.h:71
@ LWS_JOSE_ENCTYPE_AES_ECB
Definition: lws-jose.h:72
@ LWS_JOSE_ENCTYPE_AES_GCM
Definition: lws-jose.h:75
@ LWS_JOSE_ENCTYPE_AES_CFB8
Definition: lws-jose.h:70
@ LWS_JOSE_ENCTYPE_RSASSA_PKCS1_OAEP
Definition: lws-jose.h:62
@ LWS_JOSE_ENCTYPE_AES_OFB
Definition: lws-jose.h:73
@ LWS_JOSE_ENCTYPE_NONE
Definition: lws-jose.h:59
@ LWS_JOSE_ENCTYPE_AES_XTS
Definition: lws-jose.h:74
@ LWS_JOSE_ENCTYPE_ECDSA
Definition: lws-jose.h:65
@ LWS_JOSE_ENCTYPE_ECDHES
Definition: lws-jose.h:66
@ LWS_JOSE_ENCTYPE_RSASSA_PKCS1_PSS
Definition: lws-jose.h:63
@ LWS_JOSE_ENCTYPE_RSASSA_PKCS1_1_5
Definition: lws-jose.h:61
@ LWS_JOSE_ENCTYPE_AES_CBC
Definition: lws-jose.h:68
char edone[LWS_COUNT_JOSE_HDR_ELEMENTS]
Definition: lws-jose.h:123
unsigned short ivbits
Definition: lws-jose.h:88
struct lws_gencrypto_keyelem e[LWS_COUNT_JOSE_HDR_ELEMENTS]
Definition: lws-jose.h:118
LWS_VISIBLE LWS_EXTERN int lws_gencrypto_jwe_enc_to_definition(const char *enc, const struct lws_jose_jwe_alg **jose)
LWS_VISIBLE LWS_EXTERN int lws_jws_parse_jose(struct lws_jose *jose, const char *buf, int len, char *temp, int *temp_len)
enum lws_genhash_types hash_type
Definition: lws-jose.h:81
const char * alg
Definition: lws-jose.h:85
struct lws_gencrypto_keyelem unprot[LWS_COUNT_JOSE_HDR_ELEMENTS]
Definition: lws-jose.h:111
struct lws_jws_recpient recipient[LWS_JWS_MAX_RECIPIENTS]
Definition: lws-jose.h:120
enum lws_jose_algtype algtype_signing
Definition: lws-jose.h:83
char typ[32]
Definition: lws-jose.h:122
unsigned short keybits_min
Definition: lws-jose.h:87