Skip to content

Commit

Permalink
Support of pkcs12 certificate in memory with libcurl setopt, introduc…
Browse files Browse the repository at this point in the history 
…e curl_blob
  • Loading branch information
@gvollant
gvollant committed May 15, 2020
1 parent 8df4554 commit c92a862
Show file tree
Hide file tree
Showing 21 changed files with 974 additions and 130 deletions.
10 changes: 10 additions & 0 deletions docs/libcurl/curl_easy_setopt.3
View file
Expand Up @@ -506,16 +506,24 @@ Sets the interval at which connection upkeep are performed. See
.SH SSL and SECURITY OPTIONS
.IP CURLOPT_SSLCERT
Client cert. See \fICURLOPT_SSLCERT(3)\fP
.IP CURLOPT_SSLCERT_BLOB
Client cert memory buffer. See \fICURLOPT_SSLCERT_BLOB(3)\fP
.IP CURLOPT_PROXY_SSLCERT
Proxy client cert. See \fICURLOPT_PROXY_SSLCERT(3)\fP
.IP CURLOPT_PROXY_SSLCERT_BLOB
Proxy client cert memory buffer. See \fICURLOPT_PROXY_SSLCERT_BLOB(3)\fP
.IP CURLOPT_SSLCERTTYPE
Client cert type. See \fICURLOPT_SSLCERTTYPE(3)\fP
.IP CURLOPT_PROXY_SSLCERTTYPE
Proxy client cert type. See \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP
.IP CURLOPT_SSLKEY
Client key. See \fICURLOPT_SSLKEY(3)\fP
.IP CURLOPT_SSLKEY_BLOB
Client key memory buffer. See \fICURLOPT_SSLKEY_BLOB(3)\fP
.IP CURLOPT_PROXY_SSLKEY
Proxy client key. See \fICURLOPT_PROXY_SSLKEY(3)\fP
.IP CURLOPT_PROXY_SSLKEY_BLOB
Proxy client key. See \fICURLOPT_PROXY_SSLKEY_BLOB(3)\fP
.IP CURLOPT_SSLKEYTYPE
Client key type. See \fICURLOPT_SSLKEYTYPE(3)\fP
.IP CURLOPT_PROXY_SSLKEYTYPE
Expand Down Expand Up @@ -554,6 +562,8 @@ CA cert bundle. See \fICURLOPT_CAINFO(3)\fP
Proxy CA cert bundle. See \fICURLOPT_PROXY_CAINFO(3)\fP
.IP CURLOPT_ISSUERCERT
Issuer certificate. See \fICURLOPT_ISSUERCERT(3)\fP
.IP CURLOPT_ISSUERCERT_BLOB
Issuer certificate memory buffer. See \fICURLOPT_ISSUERCERT_BLOB(3)\fP
.IP CURLOPT_CAPATH
Path to CA cert bundle. See \fICURLOPT_CAPATH(3)\fP
.IP CURLOPT_PROXY_CAPATH
Expand Down
75 changes: 75 additions & 0 deletions docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.3
View file
@@ -0,0 +1,75 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2014, 2017, 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.haxx.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_ISSUERCERT_BLOB 3 "24 Jun 2020" "libcurl 7.71.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_ISSUERCERT_BLOB \- issuer SSL certificate from memory blob
.SH SYNOPSIS
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ISSUERCERT_BLOB, struct curl_blob *stblob);
.SH DESCRIPTION
Pass a pointer to a curl_blob structure, which contain information (pointer and
size) about a memory block with binary data of a CA certificate in PEM
format. If the option is set, an additional check against the peer
certificate is performed to verify the issuer is indeed the one
associated with the certificate provided by the option. This additional check
is useful in multi-level PKI where one needs to enforce that the peer
certificate is from a specific branch of the tree.

This option makes sense only when used in combination with the
\fICURLOPT_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the check is
not considered as failure.

A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option,
which is returned if the setup of the SSL/TLS session has failed due to a
mismatch with the issuer of peer certificate (\fICURLOPT_SSL_VERIFYPEER(3)\fP
has to be set too for the check to fail). (Added in 7.19.0)

If the blob is initialized with flags member of struct curl_blob set as
CURL_BLOB_COPY, the application does not have to keep the buffer
around after setting this.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS-based protocols
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
struct curl_blob stblob;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
stblob.data = certificateData;
stblob.len = filesize;
stblob.flags = CURL_BLOB_COPY;
curl_easy_setopt(curl, CURLOPT_ISSUERCERT_BLOB, &stblob);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in libcurl 7.71.0. This option is supported by the OpenSSL 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_CRLFILE "(3), " CURLOPT_SSL_VERIFYPEER "(3), "
68 changes: 68 additions & 0 deletions docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.3
View file
@@ -0,0 +1,68 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2020, 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.haxx.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_SSLCERT_BLOB 3 "24 Jun 2020" "libcurl 7.71.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_SSLCERT_BLOB \- set SSL proxy client certificate from memory blob
.SH SYNOPSIS
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLCERT_BLOB, struct curl_blob *stblob);
.SH DESCRIPTION
Pass a pointer to a curl_blob structure, which contain information (pointer and
size) about a memory block with binary data of certificate used to connect
to the HTTPS proxy. The format must be "P12" on Secure Transport or Schannel.
The format must be "P12" or "PEM" on OpenSSL.
The string "P12" or "PEM" must be specified with \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP.

If the blob is initialized with flags member of struct curl_blob set as
CURL_BLOB_COPY, the application does not have to keep the buffer
around after setting this.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
struct curl_blob stblob;
stblob.data = certificateData;
stblob.len = filesize;
stblob.flags = CURL_BLOB_COPY;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy");
curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem");
curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret");
curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT_BLOB, &stblob);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in libcurl 7.71.0. This option is supported by the OpenSSL, Secure
Transport and Schannel backends.
.SH RETURN VALUE
Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_SSLCERTTYPE "(3), " CURLOPT_PROXY_SSLKEY "(3), "
70 changes: 70 additions & 0 deletions docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.3
View file
@@ -0,0 +1,70 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2020, 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.haxx.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_SSLKEY_BLOB 3 "24 Jun 2020" "libcurl 7.71.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_SSLKEY_BLOB \- specify private keyfile for TLS and SSL proxy
client cert from memory blob
.SH SYNOPSIS
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLKEY_BLOB, struct curl_blob *stblob);
.SH DESCRIPTION
Pass a pointer to a curl_blob structure, which contain information (pointer and
size) about a memory block with binary data of private key for connecting to
the HTTPS proxy. Compatible with OpenSSL.
The format (like "PEM") must be specified with \fICURLOPT_PROXY_SSLKEYTYPE(3)\fP.

If the blob is initialized with flags member of struct curl_blob set as
CURL_BLOB_COPY, the application does not have to keep the buffer
around after setting this.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
struct curl_blob stblob;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy");
stblob.data = certificateData;
stblob.len = filesize;
stblob.flags = CURL_BLOB_COPY;
curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT_BLOB, &stblob);
curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERTTYPE, "PEM");
stblob.data = privateKeyData;
stblob.len = privateKeySize;
curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY_BLOB, &stblob);
curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in libcurl 7.71.0. This option is supported by the OpenSSL backends.
.SH RETURN VALUE
Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSLKEYTYPE "(3), " CURLOPT_SSLKEY "(3), "
10 changes: 6 additions & 4 deletions docs/libcurl/opts/CURLOPT_SSLCERT.3
View file
Expand Up @@ -38,15 +38,17 @@ you wish to authenticate with as it is named in the security database. If you
want to use a file from the current directory, please precede it with "./"
prefix, in order to avoid confusion with a nickname.

(Schannel only) Client certificates must be specified by a path expression to
a certificate store. (Loading PFX is not supported; you can import it to a
store first). You can use "<store location>\\<store name>\\<thumbprint>" to
refer to a certificate in the system certificates store, for example,
(Schannel only) Client certificates can be specified by a path expression to
a certificate store. (You can import PFX to a store first). You can use
"<store location>\\<store name>\\<thumbprint>" to refer to a certificate
in the system certificates store, for example,
"CurrentUser\\MY\\934a7ac6f8a5d579285a74fa61e19f23ddfe8d7a". Thumbprint is
usually a SHA-1 hex string which you can see in certificate details. Following
store locations are supported: CurrentUser, LocalMachine, CurrentService,
Services, CurrentUserGroupPolicy, LocalMachineGroupPolicy,
LocalMachineEnterprise.
Schannel also support P12 certificate file, with the string "P12" specified
with \fICURLOPT_SSLCERTTYPE(3)\fP.

When using a client certificate, you most likely also need to provide a
private key with \fICURLOPT_SSLKEY(3)\fP.
Expand Down
67 changes: 67 additions & 0 deletions docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.3
View file
@@ -0,0 +1,67 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2020, 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.haxx.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_SSLCERT_BLOB 3 "24 Jun 2020" "libcurl 7.71.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSLCERT_BLOB \- set SSL client certificate from memory blob
.SH SYNOPSIS
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERT_BLOB, struct curl_blob *stblob);
.SH DESCRIPTION
Pass a pointer to a curl_blob structure, which contain information (pointer and
size) about a memory block with binary data of certificate. The format
must be "P12" on Secure Transport or Schannel. The format must be "P12"
or "PEM" on OpenSSL, .
The string "P12" or "PEM" must be specified with \fICURLOPT_SSLCERTTYPE(3)\fP.

If the blob is initialized with flags member of struct curl_blob set as
CURL_BLOB_COPY, the application does not have to keep the buffer
around after setting this.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
struct curl_blob stblob;
stblob.data = certificateData;
stblob.len = filesize;
stblob.flags = CURL_BLOB_COPY;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_SSLCERT_BLOB, &stblob);
curl_easy_setopt(curl, CURLOPT_SSLCERTTYPE, "P12");
curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in libcurl 7.71.0. This option is supported by the OpenSSL, Secure
Transport and Schannel backends.
.SH RETURN VALUE
Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSLCERTTYPE "(3), " CURLOPT_SSLKEY "(3), "

0 comments on commit c92a862

Please sign in to comment.