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