docs: indicate http.sslCertType and sslKeyType

PATCH In review Andrew Carter via GitGitGadget 4 participants 9 messages Jan 23, 2025 – Feb 5, 2025 Documentation

lore

Share & tools

lore

Andrew Carter via GitGitGadget

author

2025-01-23 00:16 UTC #0 lore raw

PATCH 1/1 docs: indicate http.sslCertType and sslKeyType

From: Andrew Carter <[email protected]>

These useful config options were added in 0a01d41ee4c but lacked documentation.

Signed-off-by Andrew Carter <[email protected]>

---
document http.sslCertType and sslKeyType

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1854%2Fplentydone%2Fcurl-cert-options-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1854/plentydone/curl-cert-options-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1854

 Documentation/config/http.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)

Documentation/config/http.txt +12 -0

index a14371b5c96..cd39e182527 100644
@@ -216,6 +216,18 @@ http.sslBackend::
 	This option is ignored if cURL lacks support for choosing the SSL
 	backend at runtime.
 
+http.sslCertType::
+	Type of client certificate used when fetching or pushing over HTTPS.
+	(e.g. "PEM", "DER", or "P12"). See also libcurl `CURLOPT_SSLCERTTYPE`
+	Can be overridden by the `GIT_SSL_CERT_TYPE` environment variable.
+
+http.sslKeyType::
+	Type of client private key used when fetching or pushing over HTTPS.
+	(e.g. "PEM", "DER", or "ENG"). Particularly useful when set to "ENG"
+	for authenticating with PKCS#11 tokens. See also libcurl
+	`CURLOPT_SSLCERTTYPE` . Can be overridden by the `GIT_SSL_KEY_TYPE`
+	environment variable.
+
 http.schannelCheckRevoke::
 	Used to enforce or disable certificate revocation checks in cURL
 	when http.sslBackend is set to "schannel". Defaults to `true` if

base-commit: 4e746b1a31f9f0036032b6f94279cf16fb363203

Signature · 1 line

gitgitgadget

brian m. carlson

2025-01-23 00:34 UTC #1 lore raw

Quoted 9 lines · Andrew Carter via GitGitGadget

Documentation/config/http.txt +1 -0

index a14371b5c96..cd39e182527 100644
@@ -216,6 +216,18 @@ http.sslBackend::
 	This option is ignored if cURL lacks support for choosing the SSL
 	backend at runtime.
 
+http.sslCertType::

Documentation/config/http.txt http.sslBackend:: · line 229

Quoted 10 lines

Documentation/config/http.txt +10 -0

+	Type of client certificate used when fetching or pushing over HTTPS.
+	(e.g. "PEM", "DER", or "P12"). See also libcurl `CURLOPT_SSLCERTTYPE`
+	Can be overridden by the `GIT_SSL_CERT_TYPE` environment variable.
+
+http.sslKeyType::
+	Type of client private key used when fetching or pushing over HTTPS.
+	(e.g. "PEM", "DER", or "ENG"). Particularly useful when set to "ENG"
+	for authenticating with PKCS#11 tokens. See also libcurl
+	`CURLOPT_SSLCERTTYPE` . Can be overridden by the `GIT_SSL_KEY_TYPE`
+	environment variable.

Are there any particular limitations on these values that are platform- or backend-specific that we should document? For instance, I seem to recall that at some point PKCS#12 files were limited to schannel or Windows, although I could be mistaken.

Do we also have documentation for whatever engine parameter is required according to the libcurl documentation?

Signature · 2 lines

brian m. carlson (they/them or he/him)
Toronto, Ontario, CA

Junio C Hamano

2025-01-23 17:43 UTC #2 lore raw

Quoted 26 lines · brian m. carlson

Quoted 9 lines · Andrew Carter via GitGitGadget
Documentation/config/http.txt +1 -0
index a14371b5c96..cd39e182527 100644
@@ -216,6 +216,18 @@ http.sslBackend::
 	This option is ignored if cURL lacks support for choosing the SSL
 	backend at runtime.
 
+http.sslCertType::
Documentation/config/http.txt http.sslBackend:: · line 229
Quoted 10 lines
Documentation/config/http.txt +10 -0
+	Type of client certificate used when fetching or pushing over HTTPS.
+	(e.g. "PEM", "DER", or "P12"). See also libcurl `CURLOPT_SSLCERTTYPE`
+	Can be overridden by the `GIT_SSL_CERT_TYPE` environment variable.
+
+http.sslKeyType::
+	Type of client private key used when fetching or pushing over HTTPS.
+	(e.g. "PEM", "DER", or "ENG"). Particularly useful when set to "ENG"
+	for authenticating with PKCS#11 tokens. See also libcurl
+	`CURLOPT_SSLCERTTYPE` . Can be overridden by the `GIT_SSL_KEY_TYPE`
+	environment variable.
Are there any particular limitations on these values that are platform- or backend-specific that we should document? For instance, I seem to recall that at some point PKCS#12 files were limited to schannel or Windows, although I could be mistaken.

Quoted 2 lines

Do we also have documentation for whatever engine parameter is required according to the libcurl documentation?

Both are very good points.

I went back to the original thread that added the change cited in the proposed log message [*1*], hoping that maybe somebody brought up caveats but didn't find anything relevant other than that we punted to add tests for this since it was too cumbersome to set up.

Note to Andrew, when referring to an existing commit in your proposed log message, please do not just write its abbreviated commit object name, like 0a01d41e.

Instead, use it in "git show -s --format=reference 0a01d41e" to obtain something like

0a01d41ee4 (http: add support for different sslcert and sslkey types., 2023-03-20)

that would help people to immediately see what the change was about and how old it was.

Thanks.

[Reference]

*1* https://lore.kernel.org/git/[email protected]/

Andrew Carter

2025-01-25 06:38 UTC #3 lore raw

Quoted 49 lines · Junio C Hamano

Quoted 25 lines · brian m. carlson
Quoted 9 lines · Andrew Carter via GitGitGadget
Documentation/config/http.txt +1 -0
index a14371b5c96..cd39e182527 100644
@@ -216,6 +216,18 @@ http.sslBackend::
  	This option is ignored if cURL lacks support for choosing the SSL
  	backend at runtime.
 
+http.sslCertType::
Documentation/config/http.txt http.sslBackend:: · line 229
Quoted 10 lines
Documentation/config/http.txt +10 -0
+	Type of client certificate used when fetching or pushing over HTTPS.
+	(e.g. "PEM", "DER", or "P12"). See also libcurl `CURLOPT_SSLCERTTYPE`
+	Can be overridden by the `GIT_SSL_CERT_TYPE` environment variable.
+
+http.sslKeyType::
+	Type of client private key used when fetching or pushing over HTTPS.
+	(e.g. "PEM", "DER", or "ENG"). Particularly useful when set to "ENG"
+	for authenticating with PKCS#11 tokens. See also libcurl
+	`CURLOPT_SSLCERTTYPE` . Can be overridden by the `GIT_SSL_KEY_TYPE`
+	environment variable.
Are there any particular limitations on these values that are platform- or backend-specific that we should document? For instance, I seem to recall that at some point PKCS#12 files were limited to schannel or Windows, although I could be mistaken.
Quoted 2 lines
Do we also have documentation for whatever engine parameter is required according to the libcurl documentation?
Both are very good points.
I went back to the original thread that added the change cited in the proposed log message [*1*], hoping that maybe somebody brought up caveats but didn't find anything relevant other than that we punted to add tests for this since it was too cumbersome to set up.
Note to Andrew, when referring to an existing commit in your proposed log message, please do not just write its abbreviated commit object name, like 0a01d41e.
Instead, use it in "git show -s --format=reference 0a01d41e" to obtain something like
0a01d41ee4 (http: add support for different sslcert and sslkey types., 2023-03-20)
that would help people to immediately see what the change was about and how old it was.

Quoted 6 lines

Thanks.
[Reference]
*1* https://lore.kernel.org/git/[email protected]/

Thanks for the rapid feedback!

I was leaning away from including too many libcurl-specific details in my original patch, but I see I went too far, and these options are misleading or at least hard to decipher from my initial patch.

As you mentioned, per the curl documentation [1] the supported values are fairly backend-specific.

Git doesn't currently expose the openssl "engine" option. Because the default engine in openssl is "dynamic", in my use case, just setting the SSLKEYTYPE to "ENG" and using a PKCS#11 url in the sslKey field works. I can make a patch to introduce the option if that's desired.

I have something written up that includes backend caveats, and I will submit another patch this weekend.

Thanks for the correction on the commit reference. Please correct/forgive any list etiquette mistakes.

-AC

1. https://curl.se/libcurl/c/CURLOPT_SSLKEYTYPE.html
https://curl.se/libcurl/c/CURLOPT_SSLCERTTYPE.html

Andrew Carter

2025-01-30 13:19 UTC #4 lore raw

PATCH v2 1/1 docs: indicate http.sslCertType and sslKeyType

In reply to Andrew Carter via GitGitGadget

0a01d41ee4 (http: add support for different sslcert and sslkey types., 2023-03-20) added useful SSL config options, but did not document them.

Signed-off-by Andrew Carter <[email protected]>

---
Documentation/config/http.txt | 15 +++++++++++++++

 1 file changed, 15 insertions(+)

Documentation/config/http.txt +0 -0

index a14371b5c9..38e874307b 100644
@@ -216,6 +216,21 @@ http.sslBackend::

This option is ignored if cURL lacks support for choosing the SSL backend at runtime.

+http.sslCertType::
+    Type of client certificate used when fetching or pushing over HTTPS. +    "PEM", "DER" are supported when using openssl or gnutls backends. "P12" +    is supported on "openssl", "schannel", "securetransport", and gnutls 8.11+. +    See also libcurl CURLOPT_SSLCERTTYPE. Can be overridden by the +    GIT_SSL_CERT_TYPE environment variable.
+
+http.sslKeyType::
+    Type of client private key used when fetching or pushing over HTTPS. (e.g. +    "PEM", "DER", or "ENG"). Only applicable when using "openssl" backend. "DER" +    is not supported with openssl. Particularly useful when set to "ENG" for +    authenticating with PKCS#11 tokens, with a PKCS#11 URL in sslCert option. +    See also libcurl CURLOPT_SSLCERTTYPE. Can be overridden by the +    GIT_SSL_KEY_TYPE environment variable.
+
http.schannelCheckRevoke::
     Used to enforce or disable certificate revocation checks in cURL when http.sslBackend is set to "schannel". Defaults to true if

Signature · 1 line

2.39.5 (Apple Git-154)

Junio C Hamano

2025-01-30 22:22 UTC #5 lore raw

Quoted 7 lines · Andrew Carter

0a01d41ee4 (http: add support for different sslcert and sslkey types., 2023-03-20) added useful SSL config options, but did not document them.
Signed-off-by Andrew Carter <[email protected]>
---
Documentation/config/http.txt | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

warning: Patch sent with format=flowed; space at the end of lines might be lost.
error: corrupt patch at line 10
hint: Use 'git am --show-current-patch=diff' to see the failed patch
hint: When you have resolved this problem, run "git am --continue".
hint: If you prefer to skip this patch, run "git am --skip" instead.
hint: To restore the original branch and stop patching, run "git am --abort".
hint: Disable this message with "git config set advice.mergeConflict false"
Applying: docs: indicate http.sslCertType and sslKeyType
Patch failed at 0001 docs: indicate http.sslCertType and sslKeyType

I thought that the initial iteration I received from you on Jan 23rd was just fine. Did you change some settings with your MUA? The patch is heavily whitespace damaged, with full of  .

Quoted 31 lines

Documentation/config/http.txt +0 -0
index a14371b5c9..38e874307b 100644
@@ -216,6 +216,21 @@ http.sslBackend::
     This option is ignored if cURL lacks support for choosing the SSL backend at runtime.
+http.sslCertType::
+    Type of client certificate used when fetching or pushing over HTTPS. +    "PEM", "DER" are supported when using openssl or gnutls backends. "P12" +    is supported on "openssl", "schannel", "securetransport", and gnutls 8.11+.
+    See also libcurl CURLOPT_SSLCERTTYPE. Can be overridden by the +    GIT_SSL_CERT_TYPE environment variable.
Documentation/config/http.txt +3 -0
+
+http.sslKeyType::
+    Type of client private key used when fetching or pushing over
HTTPS. (e.g.
+    "PEM", "DER", or "ENG"). Only applicable when using "openssl" backend. "DER"
+    is not supported with openssl. Particularly useful when set to "ENG" for
+    authenticating with PKCS#11 tokens, with a PKCS#11 URL in sslCert option.
+    See also libcurl CURLOPT_SSLCERTTYPE. Can be overridden by the +    GIT_SSL_KEY_TYPE environment variable.
+
http.schannelCheckRevoke::
     Used to enforce or disable certificate revocation checks in cURL when http.sslBackend is set to "schannel". Defaults to true if

Andrew Carter

2025-02-05 05:46 UTC #6 lore raw

Quoted 47 lines · Junio C Hamano

Quoted 7 lines · Andrew Carter
0a01d41ee4 (http: add support for different sslcert and sslkey types., 2023-03-20) added useful SSL config options, but did not document them.
Signed-off-by Andrew Carter <[email protected]>
---
  Documentation/config/http.txt | 15 +++++++++++++++
  1 file changed, 15 insertions(+)
warning: Patch sent with format=flowed; space at the end of lines might be lost.
error: corrupt patch at line 10
hint: Use 'git am --show-current-patch=diff' to see the failed patch
hint: When you have resolved this problem, run "git am --continue".
hint: If you prefer to skip this patch, run "git am --skip" instead.
hint: To restore the original branch and stop patching, run "git am --abort".
hint: Disable this message with "git config set advice.mergeConflict false"
Applying: docs: indicate http.sslCertType and sslKeyType
Patch failed at 0001 docs: indicate http.sslCertType and sslKeyType
I thought that the initial iteration I received from you on Jan 23rd was just fine. Did you change some settings with your MUA? The patch is heavily whitespace damaged, with full of  .
Quoted 23 lines
Documentation/config/http.txt +4 -0
index a14371b5c9..38e874307b 100644
@@ -216,6 +216,21 @@ http.sslBackend::
      This option is ignored if cURL lacks support for choosing the SSL
      backend at runtime.
 
+http.sslCertType::
+    Type of client certificate used when fetching or pushing over HTTPS.
+    "PEM", "DER" are supported when using openssl or gnutls backends. "P12"
+    is supported on "openssl", "schannel", "securetransport", and
gnutls 8.11+.
+ See also libcurl CURLOPT_SSLCERTTYPE. Can be overridden by the + GIT_SSL_CERT_TYPE environment variable.
Documentation/config/http.txt +3 -0
+
+http.sslKeyType::
+    Type of client private key used when fetching or pushing over
HTTPS. (e.g.
+ "PEM", "DER", or "ENG"). Only applicable when using "openssl" backend. "DER"
+ is not supported with openssl. Particularly useful when set to "ENG" for

Quoted 8 lines

Quoted 8 lines
+    authenticating with PKCS#11 tokens, with a PKCS#11 URL in sslCert option.
+    See also libcurl CURLOPT_SSLCERTTYPE. Can be overridden by the +    GIT_SSL_KEY_TYPE environment variable.
+
http.schannelCheckRevoke::
     Used to enforce or disable certificate revocation checks in cURL when http.sslBackend is set to "schannel". Defaults to true if

Sorry for the inconvenience, and thanks for your patience.

The original message was composed by GitGitGadget. I pasted the v2 patch into Thunderbird initially, which clearly failed.

I sent a new v2 patch using git send-email, and at a glance it looks unbroken.

If further changes are needed I can get an updated patch to you with a faster turnaround now.

-AC

Junio C Hamano

2025-02-05 17:46 UTC #7 lore raw

Quoted 8 lines · Andrew Carter

Quoted 3 lines · Junio C Hamano
I thought that the initial iteration I received from you on Jan 23rd was just fine. Did you change some settings with your MUA? The patch is heavily whitespace damaged, with full of  .
...
Sorry for the inconvenience, and thanks for your patience.

Quoted 8 lines

The original message was composed by GitGitGadget. I pasted the v2 patch into Thunderbird initially, which clearly failed.
I sent a new v2 patch using git send-email, and at a glance it looks unbroken.
If further changes are needed I can get an updated patch to you with a faster turnaround now.

Thanks for your patience, too.

E-mailed patch workflow is easy for automation, once set-up correctly, but there is certain entry cost.

Queued. Let's mark it for 'next'.

Andrew Carter

2025-02-05 05:39 UTC #8 lore raw

PATCH v2 1/1 docs: indicate http.sslCertType and sslKeyType

In reply to Andrew Carter via GitGitGadget

0a01d41ee4 (http: add support for different sslcert and sslkey types., 2023-03-20) added useful SSL config options, but did not document them.

Signed-off-by Andrew Carter <[email protected]>

---
 Documentation/config/http.txt | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

Documentation/config/http.txt +15 -0

index a14371b5c9..22a8803dea 100644
@@ -216,6 +216,21 @@ http.sslBackend::
 	This option is ignored if cURL lacks support for choosing the SSL
 	backend at runtime.
 
+http.sslCertType::
+	Type of client certificate used when fetching or pushing over HTTPS.
+	"PEM", "DER" are supported when using openssl or gnutls backends. "P12"
+	is supported on "openssl", "schannel", "securetransport", and gnutls 8.11+.
+	See also libcurl `CURLOPT_SSLCERTTYPE`. Can be overridden by the
+	`GIT_SSL_CERT_TYPE` environment variable.
+
+http.sslKeyType::
+	Type of client private key used when fetching or pushing over HTTPS. (e.g.
+	"PEM", "DER", or "ENG"). Only applicable when using "openssl" backend. "DER"
+	is not supported with openssl. Particularly useful when set to "ENG" for
+	authenticating with PKCS#11 tokens, with a PKCS#11 URL in sslCert option.
+	See also libcurl `CURLOPT_SSLKEYTYPE`. Can be overridden by the
+	`GIT_SSL_KEY_TYPE` environment variable.
+
 http.schannelCheckRevoke::
 	Used to enforce or disable certificate revocation checks in cURL
 	when http.sslBackend is set to "schannel". Defaults to `true` if

Signature · 1 line

2.39.5 (Apple Git-154)