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 | |
25 | enum lws_tls_cert_info { |
26 | LWS_TLS_CERT_INFO_VALIDITY_FROM, |
27 | /**< fills .time with the time_t the cert validity started from */ |
28 | LWS_TLS_CERT_INFO_VALIDITY_TO, |
29 | /**< fills .time with the time_t the cert validity ends at */ |
30 | LWS_TLS_CERT_INFO_COMMON_NAME, |
31 | /**< fills up to len bytes of .ns.name with the cert common name */ |
32 | LWS_TLS_CERT_INFO_ISSUER_NAME, |
33 | /**< fills up to len bytes of .ns.name with the cert issuer name */ |
34 | LWS_TLS_CERT_INFO_USAGE, |
35 | /**< fills verified with a bitfield asserting the valid uses */ |
36 | LWS_TLS_CERT_INFO_VERIFIED, |
37 | /**< fills .verified with a bool representing peer cert validity, |
38 | * call returns -1 if no cert */ |
39 | LWS_TLS_CERT_INFO_OPAQUE_PUBLIC_KEY, |
40 | /**< the certificate's public key, as an opaque bytestream. These |
41 | * opaque bytestreams can only be compared with each other using the |
42 | * same tls backend, ie, OpenSSL or mbedTLS. The different backends |
43 | * produce different, incompatible representations for the same cert. |
44 | */ |
45 | LWS_TLS_CERT_INFO_DER_RAW, |
46 | /**< the certificate's raw DER representation. If it's too big, |
47 | * -1 is returned and the size will be returned in buf->ns.len. |
48 | * If the certificate cannot be found -1 is returned and 0 in |
49 | * buf->ns.len. */ |
50 | LWS_TLS_CERT_INFO_AUTHORITY_KEY_ID, |
51 | /**< If the cert has one, the key ID responsible for the signature */ |
52 | LWS_TLS_CERT_INFO_AUTHORITY_KEY_ID_ISSUER, |
53 | /**< If the cert has one, the issuer responsible for the signature */ |
54 | LWS_TLS_CERT_INFO_AUTHORITY_KEY_ID_SERIAL, |
55 | /**< If the cert has one, serial number responsible for the signature */ |
56 | LWS_TLS_CERT_INFO_SUBJECT_KEY_ID, |
57 | /**< If the cert has one, the cert's subject key ID */ |
58 | }; |
59 | |
60 | union lws_tls_cert_info_results { |
61 | unsigned int verified; |
62 | time_t time; |
63 | unsigned int usage; |
64 | struct { |
65 | int len; |
66 | /* KEEP LAST... notice the [64] is only there because |
67 | * name[] is not allowed in a union. The actual length of |
68 | * name[] is arbitrary and is passed into the api using the |
69 | * len parameter. Eg |
70 | * |
71 | * char big[1024]; |
72 | * union lws_tls_cert_info_results *buf = |
73 | * (union lws_tls_cert_info_results *)big; |
74 | * |
75 | * lws_tls_peer_cert_info(wsi, type, buf, sizeof(big) - |
76 | * sizeof(*buf) + sizeof(buf->ns.name)); |
77 | */ |
78 | char name[64]; |
79 | } ns; |
80 | }; |
81 | |
82 | struct lws_x509_cert; |
83 | struct lws_jwk; |
84 | |
85 | /** |
86 | * lws_x509_create() - Allocate an lws_x509_cert object |
87 | * |
88 | * \param x509: pointer to lws_x509_cert pointer to be set to allocated object |
89 | * |
90 | * Allocates an lws_x509_cert object and set *x509 to point to it. |
91 | */ |
92 | LWS_VISIBLE LWS_EXTERN int |
93 | lws_x509_create(struct lws_x509_cert **x509); |
94 | |
95 | /** |
96 | * lws_x509_parse_from_pem() - Read one or more x509 certs in PEM format from memory |
97 | * |
98 | * \param x509: pointer to lws_x509_cert object |
99 | * \param pem: pointer to PEM format content |
100 | * \param len: length of PEM format content |
101 | * |
102 | * Parses PEM certificates in memory into a native x509 representation for the |
103 | * TLS library. If there are multiple PEM certs concatenated, they are all |
104 | * read into the same object and exist as a "chain". |
105 | * |
106 | * IMPORTANT for compatibility with mbedtls, the last used byte of \p pem |
107 | * must be '\0' and the \p len must include it. |
108 | * |
109 | * Returns 0 if all went OK, or nonzero for failure. |
110 | */ |
111 | LWS_VISIBLE LWS_EXTERN int |
112 | lws_x509_parse_from_pem(struct lws_x509_cert *x509, const void *pem, size_t len); |
113 | |
114 | /** |
115 | * lws_x509_verify() - Validate signing relationship between one or more certs |
116 | * and a trusted CA cert |
117 | * |
118 | * \param x509: pointer to lws_x509_cert object, may contain multiple |
119 | * \param trusted: a single, trusted cert object that we are checking for |
120 | * \param common_name: NULL, or required CN (Common Name) of \p x509 |
121 | * |
122 | * Returns 0 if the cert or certs in \p x509 represent a complete chain that is |
123 | * ultimately signed by the cert in \p trusted. Returns nonzero if that's not |
124 | * the case. |
125 | */ |
126 | LWS_VISIBLE LWS_EXTERN int |
127 | lws_x509_verify(struct lws_x509_cert *x509, struct lws_x509_cert *trusted, |
128 | const char *common_name); |
129 | |
130 | /** |
131 | * lws_x509_public_to_jwk() - Copy the public key out of a cert and into a JWK |
132 | * |
133 | * \param jwk: pointer to the jwk to initialize and set to the public key |
134 | * \param x509: pointer to lws_x509_cert object that has the public key |
135 | * \param curves: NULL to disallow EC, else a comma-separated list of valid |
136 | * curves using the JWA naming, eg, "P-256,P-384,P-521". |
137 | * \param rsabits: minimum number of RSA bits required in the cert if RSA |
138 | * |
139 | * Returns 0 if JWK was set to the certificate public key correctly and the |
140 | * curve / the RSA key size was acceptable. Automatically produces an RSA or |
141 | * EC JWK depending on what the cert had. |
142 | */ |
143 | LWS_VISIBLE LWS_EXTERN int |
144 | lws_x509_public_to_jwk(struct lws_jwk *jwk, struct lws_x509_cert *x509, |
145 | const char *curves, int rsabits); |
146 | |
147 | /** |
148 | * lws_x509_jwk_privkey_pem() - Copy a private key PEM into a jwk that has the |
149 | * public part already |
150 | * |
151 | * \param cx: lws_context (for random) |
152 | * \param jwk: pointer to the jwk to initialize and set to the public key |
153 | * \param pem: pointer to PEM private key in memory |
154 | * \param len: length of PEM private key in memory |
155 | * \param passphrase: NULL or passphrase needed to decrypt private key |
156 | * |
157 | * IMPORTANT for compatibility with mbedtls, the last used byte of \p pem |
158 | * must be '\0' and the \p len must include it. |
159 | * |
160 | * Returns 0 if the private key was successfully added to the JWK, else |
161 | * nonzero if failed. |
162 | * |
163 | * The PEM image in memory is zeroed down on both successful and failed exits. |
164 | * The caller should take care to zero down passphrase if used. |
165 | */ |
166 | LWS_VISIBLE LWS_EXTERN int |
167 | lws_x509_jwk_privkey_pem(struct lws_context *cx, struct lws_jwk *jwk, |
168 | void *pem, size_t len, const char *passphrase); |
169 | |
170 | /** |
171 | * lws_x509_destroy() - Destroy a previously allocated lws_x509_cert object |
172 | * |
173 | * \param x509: pointer to lws_x509_cert pointer |
174 | * |
175 | * Deallocates an lws_x509_cert object and sets its pointer to NULL. |
176 | */ |
177 | LWS_VISIBLE LWS_EXTERN void |
178 | lws_x509_destroy(struct lws_x509_cert **x509); |
179 | |
180 | LWS_VISIBLE LWS_EXTERN int |
181 | lws_x509_info(struct lws_x509_cert *x509, enum lws_tls_cert_info type, |
182 | union lws_tls_cert_info_results *buf, size_t len); |
183 | |
184 | /** |
185 | * lws_tls_peer_cert_info() - get information from the peer's TLS cert |
186 | * |
187 | * \param wsi: the connection to query |
188 | * \param type: one of LWS_TLS_CERT_INFO_ |
189 | * \param buf: pointer to union to take result |
190 | * \param len: when result is a string, the true length of buf->ns.name[] |
191 | * |
192 | * lws_tls_peer_cert_info() lets you get hold of information from the peer |
193 | * certificate. |
194 | * |
195 | * Return 0 if there is a result in \p buf, or nonzero indicating there was no |
196 | * cert, or another problem. |
197 | * |
198 | * This function works the same no matter if the TLS backend is OpenSSL or |
199 | * mbedTLS. |
200 | */ |
201 | LWS_VISIBLE LWS_EXTERN int |
202 | lws_tls_peer_cert_info(struct lws *wsi, enum lws_tls_cert_info type, |
203 | union lws_tls_cert_info_results *buf, size_t len); |
204 | |
205 | /** |
206 | * lws_tls_vhost_cert_info() - get information from the vhost's own TLS cert |
207 | * |
208 | * \param vhost: the vhost to query |
209 | * \param type: one of LWS_TLS_CERT_INFO_ |
210 | * \param buf: pointer to union to take result |
211 | * \param len: when result is a string, the true length of buf->ns.name[] |
212 | * |
213 | * lws_tls_vhost_cert_info() lets you get hold of information from the vhost |
214 | * certificate. |
215 | * |
216 | * Return 0 if there is a result in \p buf, or nonzero indicating there was no |
217 | * cert, or another problem. |
218 | * |
219 | * This function works the same no matter if the TLS backend is OpenSSL or |
220 | * mbedTLS. |
221 | */ |
222 | LWS_VISIBLE LWS_EXTERN int |
223 | lws_tls_vhost_cert_info(struct lws_vhost *vhost, enum lws_tls_cert_info type, |
224 | union lws_tls_cert_info_results *buf, size_t len); |
225 | |
226 | /** |
227 | * lws_tls_acme_sni_cert_create() - creates a temp selfsigned cert |
228 | * and attaches to a vhost |
229 | * |
230 | * \param vhost: the vhost to acquire the selfsigned cert |
231 | * \param san_a: SAN written into the certificate |
232 | * \param san_b: second SAN written into the certificate |
233 | * |
234 | * |
235 | * Returns 0 if created and attached to the vhost. Returns nonzero if problems, |
236 | * and frees all allocations before returning. |
237 | * |
238 | * On success, any allocations are destroyed at vhost destruction automatically. |
239 | */ |
240 | LWS_VISIBLE LWS_EXTERN int |
241 | lws_tls_acme_sni_cert_create(struct lws_vhost *vhost, const char *san_a, |
242 | const char *san_b); |
243 | |
244 | /** |
245 | * lws_tls_acme_sni_csr_create() - creates a CSR and related private key PEM |
246 | * |
247 | * \param context: lws_context used for random |
248 | * \param elements: array of LWS_TLS_REQ_ELEMENT_COUNT const char * |
249 | * \param csr: buffer that will get the b64URL(ASN-1 CSR) |
250 | * \param csr_len: max length of the csr buffer |
251 | * \param privkey_pem: pointer to pointer allocated to hold the privkey_pem |
252 | * \param privkey_len: pointer to size_t set to the length of the privkey_pem |
253 | * |
254 | * Creates a CSR according to the information in \p elements, and a private |
255 | * RSA key used to sign the CSR. |
256 | * |
257 | * The outputs are the b64URL(ASN-1 CSR) into csr, and the PEM private key into |
258 | * privkey_pem. |
259 | * |
260 | * Notice that \p elements points to an array of const char *s pointing to the |
261 | * information listed in the enum above. If an entry is NULL or an empty |
262 | * string, the element is set to "none" in the CSR. |
263 | * |
264 | * Returns 0 on success or nonzero for failure. |
265 | */ |
266 | LWS_VISIBLE LWS_EXTERN int |
267 | lws_tls_acme_sni_csr_create(struct lws_context *context, const char *elements[], |
268 | uint8_t *csr, size_t csr_len, char **privkey_pem, |
269 | size_t *privkey_len); |
270 | |
271 | /** |
272 | * lws_tls_cert_updated() - update every vhost using the given cert path |
273 | * |
274 | * \param context: our lws_context |
275 | * \param certpath: the filepath to the certificate |
276 | * \param keypath: the filepath to the private key of the certificate |
277 | * \param mem_cert: copy of the cert in memory |
278 | * \param len_mem_cert: length of the copy of the cert in memory |
279 | * \param mem_privkey: copy of the private key in memory |
280 | * \param len_mem_privkey: length of the copy of the private key in memory |
281 | * |
282 | * Checks every vhost to see if it is the using certificate described by the |
283 | * the given filepaths. If so, it attempts to update the vhost ssl_ctx to use |
284 | * the new certificate. |
285 | * |
286 | * Returns 0 on success or nonzero for failure. |
287 | */ |
288 | LWS_VISIBLE LWS_EXTERN int |
289 | lws_tls_cert_updated(struct lws_context *context, const char *certpath, |
290 | const char *keypath, |
291 | const char *mem_cert, size_t len_mem_cert, |
292 | const char *mem_privkey, size_t len_mem_privkey); |
293 | |
294 | |