From cabcf403ed6880014e2be1030785e455cbab6ab4 Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Sat, 12 Mar 2022 18:23:12 -0500 Subject: [PATCH] docs/opts: Mention Schannel client cert type is P12 Schannel backend code behaves same as Secure Transport, it expects a P12 certificate file or the name of a certificate already in the user's OS key store. Also, both backends ignore CURLOPT_SSLKEY (tool: --key) because they expect the private key to already be available from the keystore or P12 certificate. Ref: https://github.com/curl/curl/discussions/8581#discussioncomment-2337260 Closes https://github.com/curl/curl/pull/8587 --- docs/cmdline-opts/cert-type.d | 8 ++++++-- docs/cmdline-opts/key.d | 5 +++++ docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.3 | 7 ++++--- docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 | 6 +++--- docs/libcurl/opts/CURLOPT_SSLCERTTYPE.3 | 10 ++++++---- docs/libcurl/opts/CURLOPT_SSLKEY.3 | 6 +++--- src/tool_listhelp.c | 2 +- 7 files changed, 28 insertions(+), 16 deletions(-) diff --git a/docs/cmdline-opts/cert-type.d b/docs/cmdline-opts/cert-type.d index a31f40ef53..ead0e18f34 100644 --- a/docs/cmdline-opts/cert-type.d +++ b/docs/cmdline-opts/cert-type.d @@ -1,13 +1,17 @@ Long: cert-type Protocols: TLS Arg: -Help: Certificate type (DER/PEM/ENG) +Help: Certificate type (DER/PEM/ENG/P12) See-also: cert key key-type Category: tls Example: --cert-type PEM --cert file $URL Added: 7.9.3 --- Tells curl what type the provided client certificate is using. PEM, DER, ENG -and P12 are recognized types. If not specified, PEM is assumed. +and P12 are recognized types. + +The default type depends on the TLS backend and is usually PEM, however for +Secure Transport and Schannel it is P12. If --cert is a pkcs11: URI then ENG is +the default type. If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/key.d b/docs/cmdline-opts/key.d index 8d9c1136cb..4dd072a159 100644 --- a/docs/cmdline-opts/key.d +++ b/docs/cmdline-opts/key.d @@ -18,4 +18,9 @@ PKCS#11 URI. If a PKCS#11 URI is provided, then the --engine option will be set as "pkcs11" if none was provided and the --key-type option will be set as "ENG" if none was provided. +If curl is built against Secure Transport or Schannel then this option is +ignored for TLS protocols (HTTPS, etc). Those backends expect the private key +to be already present in the keychain or PKCS#12 file containing the +certificate. + If this option is used several times, the last one will be used. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.3 index 1cf519ddf2..d0cb1521bb 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.3 @@ -33,9 +33,10 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLCERTTYPE, char *type); Pass a pointer to a null-terminated string as parameter. The string should be the format of your client certificate used when connecting to an HTTPS proxy. -Supported formats are "PEM" and "DER", except with Secure Transport. OpenSSL -(versions 0.9.3 and later) and Secure Transport (on iOS 5 or later, or OS X -10.7 or later) also support "P12" for PKCS#12-encoded files. +Supported formats are "PEM" and "DER", except with Secure Transport or +Schannel. OpenSSL (versions 0.9.3 and later), Secure Transport (on iOS 5 or +later, or OS X 10.7 or later) and Schannel support "P12" for PKCS#12-encoded +files. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 index 6c6c77e100..f873d7d139 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 @@ -35,9 +35,9 @@ the file name of your private key used for connecting to the HTTPS proxy. The default format is "PEM" and can be changed with \fICURLOPT_PROXY_SSLKEYTYPE(3)\fP. -(iOS and Mac OS X only) This option is ignored if curl was built against -Secure Transport. Secure Transport expects the private key to be already -present in the keychain or PKCS#12 file containing the certificate. +(Windows, iOS and Mac OS X) This option is ignored by Secure Transport and +Schannel SSL backends because they expect the private key to be already present +in the keychain or PKCS#12 file containing the certificate. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.3 b/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.3 index 051a7b15c7..d70d6324f8 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.3 +++ b/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.3 @@ -31,10 +31,12 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERTTYPE, char *type); .fi .SH DESCRIPTION Pass a pointer to a null-terminated string as parameter. The string should be -the format of your certificate. Supported formats are "PEM" and "DER", except -with Secure Transport. OpenSSL (versions 0.9.3 and later) and Secure Transport -(on iOS 5 or later, or OS X 10.7 or later) also support "P12" for -PKCS#12-encoded files. +the format of your certificate. + +Supported formats are "PEM" and "DER", except with Secure Transport or +Schannel. OpenSSL (versions 0.9.3 and later), Secure Transport (on iOS 5 or +later, or OS X 10.7 or later) and Schannel support "P12" for PKCS#12-encoded +files. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_SSLKEY.3 b/docs/libcurl/opts/CURLOPT_SSLKEY.3 index 3685596dbd..6258522d89 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEY.3 +++ b/docs/libcurl/opts/CURLOPT_SSLKEY.3 @@ -34,9 +34,9 @@ Pass a pointer to a null-terminated string as parameter. The string should be the file name of your private key. The default format is "PEM" and can be changed with \fICURLOPT_SSLKEYTYPE(3)\fP. -(iOS and Mac OS X only) This option is ignored if curl was built against -Secure Transport. Secure Transport expects the private key to be already -present in the keychain or PKCS#12 file containing the certificate. +(Windows, iOS and Mac OS X) This option is ignored by Secure Transport and +Schannel SSL backends because they expect the private key to be already present +in the keychain or PKCS#12 file containing the certificate. The application does not have to keep the string around after setting this option. diff --git a/src/tool_listhelp.c b/src/tool_listhelp.c index d67e8563bf..8575146292 100644 --- a/src/tool_listhelp.c +++ b/src/tool_listhelp.c @@ -62,7 +62,7 @@ const struct helptxt helptext[] = { "Verify the status of the server cert via OCSP-staple", CURLHELP_TLS}, {" --cert-type ", - "Certificate type (DER/PEM/ENG)", + "Certificate type (DER/PEM/ENG/P12)", CURLHELP_TLS}, {" --ciphers ", "SSL ciphers to use", -- 2.47.3