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
25enum 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
60union 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
82struct lws_x509_cert;
83struct 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 */
92LWS_VISIBLE LWS_EXTERN int
93lws_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 */
111LWS_VISIBLE LWS_EXTERN int
112lws_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 */
126LWS_VISIBLE LWS_EXTERN int
127lws_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 */
143LWS_VISIBLE LWS_EXTERN int
144lws_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 */
166LWS_VISIBLE LWS_EXTERN int
167lws_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 */
177LWS_VISIBLE LWS_EXTERN void
178lws_x509_destroy(struct lws_x509_cert **x509);
179
180LWS_VISIBLE LWS_EXTERN int
181lws_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 */
201LWS_VISIBLE LWS_EXTERN int
202lws_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 */
222LWS_VISIBLE LWS_EXTERN int
223lws_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 */
240LWS_VISIBLE LWS_EXTERN int
241lws_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 */
266LWS_VISIBLE LWS_EXTERN int
267lws_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 */
288LWS_VISIBLE LWS_EXTERN int
289lws_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