SSL: support in-memory CA certs for some backends

- New options CURLOPT_CAINFO_BLOB and CURLOPT_PROXY_CAINFO_BLOB to
  specify in-memory PEM certificates for OpenSSL, Schannel (Windows)
  and Secure Transport (Apple) SSL backends.

Prior to this change PEM certificates could only be imported from a file
and not from memory.

Co-authored-by: moparisthebest@users.noreply.github.com

Ref: https://github.com/curl/curl/pull/4679
Ref: https://github.com/curl/curl/pull/5677
Ref: https://github.com/curl/curl/pull/6109

Closes https://github.com/curl/curl/pull/6662

5 files changed, 148 insertions, 2 deletions

diff --git a/docs/libcurl/opts/CURLOPT_CAINFO.3 b/docs/libcurl/opts/CURLOPT_CAINFO.3
index e7eb8b01d..fe7c8187f 100644
--- a/docs/libcurl/opts/CURLOPT_CAINFO.3
+++ b/docs/libcurl/opts/CURLOPT_CAINFO.3
@@ -79,5 +79,5 @@ option is ignored. Schannel support added in libcurl 7.60.
 Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
 CURLE_OUT_OF_MEMORY if there was insufficient heap space.
 .SH "SEE ALSO"
-.BR CURLOPT_CAPATH "(3), "
+.BR CURLOPT_CAINFO_BLOB "(3), " CURLOPT_CAPATH "(3), "
 .BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), "
diff --git a/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.3 b/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.3
new file mode 100644
index 000000000..c980d99d0
--- /dev/null
+++ b/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.3
@@ -0,0 +1,68 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" *
+.\" * This software is licensed as described in the file COPYING, which
+.\" * you should have received as part of this distribution. The terms
+.\" * are also available at https://curl.se/docs/copyright.html.
+.\" *
+.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+.\" * copies of the Software, and permit persons to whom the Software is
+.\" * furnished to do so, under the terms of the COPYING file.
+.\" *
+.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+.\" * KIND, either express or implied.
+.\" *
+.\" **************************************************************************
+.\"
+.TH CURLOPT_CAINFO_BLOB 3 "31 March 2021" "libcurl 7.77.0" "curl_easy_setopt options"
+.SH NAME
+CURLOPT_CAINFO_BLOB \- Certificate Authority (CA) bundle in PEM format
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CAINFO_BLOB, struct curl_blob *stblob);
+.SH DESCRIPTION
+Pass a pointer to a curl_blob structure, which contains information (pointer
+and size) about a memory block with binary data of PEM encoded content holding
+one or more certificates to verify the HTTPS server with.
+
+If \fICURLOPT_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the
+server's certificate, \fICURLOPT_CAINFO_BLOB(3)\fP is not needed.
+
+This option overrides \fICURLOPT_CAINFO(3)\fP.
+.SH DEFAULT
+NULL
+.SH PROTOCOLS
+All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
+.SH EXAMPLE
+.nf
+char *strpem; /* strpem must point to a PEM string */
+CURL *curl = curl_easy_init();
+if(curl) {
+  struct curl_blob blob;
+  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
+  blob.data = strpem;
+  blob.len = strlen(strpem);
+  blob.flags = CURL_BLOB_COPY;
+  curl_easy_setopt(curl, CURLOPT_CAINFO_BLOB, &blob);
+  ret = curl_easy_perform(curl);
+  curl_easy_cleanup(curl);
+}
+.fi
+.SH AVAILABILITY
+Added in 7.77.0.
+
+This option is supported by the OpenSSL, Secure
+Transport and Schannel backends.
+.SH RETURN VALUE
+Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
+CURLE_OUT_OF_MEMORY if there was insufficient heap space.
+.SH "SEE ALSO"
+.BR CURLOPT_CAINFO "(3), " CURLOPT_CAPATH "(3), "
+.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), "
diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3
index 17a870bb3..b0434d2b9 100644
--- a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3
+++ b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3
@@ -77,7 +77,8 @@ https://curl.se/docs/ssl-compared.html
 Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
 CURLE_OUT_OF_MEMORY if there was insufficient heap space.
 .SH "SEE ALSO"
-.BR CURLOPT_PROXY_CAPATH "(3), "
+.BR CURLOPT_PROXY_CAINFO_BLOB "(3), " CURLOPT_PROXY_CAPATH "(3), "
 .BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), " CURLOPT_PROXY_SSL_VERIFYHOST "(3), "
+.BR CURLOPT_CAINFO "(3), " CURLOPT_CAINFO_BLOB "(3), "
 .BR CURLOPT_CAPATH "(3), "
 .BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), "
diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.3 b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.3
new file mode 100644
index 000000000..d1c15fcb2
--- /dev/null
+++ b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.3
@@ -0,0 +1,75 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" *
+.\" * This software is licensed as described in the file COPYING, which
+.\" * you should have received as part of this distribution. The terms
+.\" * are also available at https://curl.se/docs/copyright.html.
+.\" *
+.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+.\" * copies of the Software, and permit persons to whom the Software is
+.\" * furnished to do so, under the terms of the COPYING file.
+.\" *
+.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+.\" * KIND, either express or implied.
+.\" *
+.\" **************************************************************************
+.\"
+.TH CURLOPT_PROXY_CAINFO_BLOB 3 "31 March 2021" "libcurl 7.77.0" "curl_easy_setopt options"
+.SH NAME
+CURLOPT_PROXY_CAINFO_BLOB \- proxy Certificate Authority (CA) bundle in PEM format
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CAINFO_BLOB, struct curl_blob *stblob);
+.SH DESCRIPTION
+This option is for connecting to an HTTPS proxy, not an HTTPS server.
+
+Pass a pointer to a curl_blob structure, which contains information (pointer
+and size) about a memory block with binary data of PEM encoded content holding
+one or more certificates to verify the HTTPS proxy with.
+
+If \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the
+server's certificate, \fICURLOPT_PROXY_CAINFO_BLOB(3)\fP is not needed.
+
+This option overrides \fICURLOPT_PROXY_CAINFO(3)\fP.
+.SH DEFAULT
+NULL
+.SH PROTOCOLS
+Used with HTTPS proxy
+.SH EXAMPLE
+.nf
+char *strpem; /* strpem must point to a PEM string */
+CURL *curl = curl_easy_init();
+if(curl) {
+  struct curl_blob blob;
+  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
+  /* using an HTTPS proxy */
+  curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443");
+  blob.data = strpem;
+  blob.len = strlen(strpem);
+  blob.flags = CURL_BLOB_COPY;  
+  curl_easy_setopt(curl, CURLOPT_PROXY_CAINFO_BLOB, &blob);
+  ret = curl_easy_perform(curl);
+  curl_easy_cleanup(curl);
+}
+.fi
+.SH AVAILABILITY
+Added in 7.77.0.
+
+This option is supported by the OpenSSL, Secure
+Transport and Schannel backends.
+.SH RETURN VALUE
+Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
+CURLE_OUT_OF_MEMORY if there was insufficient heap space.
+.SH "SEE ALSO"
+.BR CURLOPT_PROXY_CAINFO "(3), " CURLOPT_PROXY_CAPATH "(3), "
+.BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), " CURLOPT_PROXY_SSL_VERIFYHOST "(3), "
+.BR CURLOPT_CAINFO "(3), " CURLOPT_CAINFO_BLOB "(3), "
+.BR CURLOPT_CAPATH "(3), "
+.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), "
diff --git a/docs/libcurl/opts/Makefile.inc b/docs/libcurl/opts/Makefile.inc
index 69e241862..1181331b9 100644
--- a/docs/libcurl/opts/Makefile.inc
+++ b/docs/libcurl/opts/Makefile.inc
@@ -115,6 +115,7 @@ man_MANS =                                      \
   CURLOPT_AUTOREFERER.3                         \
   CURLOPT_BUFFERSIZE.3                          \
   CURLOPT_CAINFO.3                              \
+  CURLOPT_CAINFO_BLOB.3                         \
   CURLOPT_CAPATH.3                              \
   CURLOPT_CERTINFO.3                            \
   CURLOPT_CHUNK_BGN_FUNCTION.3                  \
@@ -267,6 +268,7 @@ man_MANS =                                      \
   CURLOPT_PROXYUSERNAME.3                       \
   CURLOPT_PROXYUSERPWD.3                        \
   CURLOPT_PROXY_CAINFO.3                        \
+  CURLOPT_PROXY_CAINFO_BLOB.3                   \
   CURLOPT_PROXY_CAPATH.3                        \
   CURLOPT_PROXY_CRLFILE.3                       \
   CURLOPT_PROXY_KEYPASSWD.3                     \