Repository navigation
Conversation
|
|
||
| The default value for this can be figured out with CURLINFO_CAINFO(3). | ||
|
|
||
| This option has no effect on LDAP connections when libcurl uses the legacy LDAP |
There was a problem hiding this comment.
How many LDAP users do you think this affects? Are they going to know what "legacy LDAP" means? Also it could be explained and summarized rather than this whole paragraph, example
This option has no effect on LDAP connections when libcurl uses SomeOldLDAP < 4.5.6. (The end)
IMO there's such a thing as too much documentation,
There was a problem hiding this comment.
Good point. "legacy LDAP" is not a good term in user documentation as nobody will know who uses that...
There was a problem hiding this comment.
"legacy LDAP" is a term already used in another manual page
(via f2692b5), and
a source file originally (via f646e90)
hence I let it pass. But yeah, I also don't like it. Perhaps spelling
out WinLDAP and Apple LDAP would work? (...there is also
IBMLDAP, but omitting that seems fine).
This information here, isn't necessarily obvious to everyone,
past myself included, and I had to spell it out in the past when
it came up in Issues IIRC. And almost this existing text is already
present in CURLOPT_PINNEDPUBLICKEY man page (also from
Joshua).
There was a problem hiding this comment.
And almost this existing text is already
present in CURLOPT_PINNEDPUBLICKEY man page (also from
Joshua).
I think that existing text is also too verbose:
This option has no effect on LDAP connections when libcurl uses the legacy LDAP backend. That backend manages TLS independently of curl's TLS layer. When libcurl is built with USE_OPENLDAP, the OpenLDAP backend routes TLS through curl's layer and this option is honored.
I wonder how much detail the user needs. Not a fan of spelling out what would work, can't we just point out what specific versions do not work? Is this known? Ideally the entire thing could be boiled down to a single sentence.
Also, this PR says:
On OpenLDAP >= 2.5, the TLS context the legacy LDAP backend's ldaps:// connection actually uses is process-global, not per-handle. Verified empirically (OpenLDAP 2.7.1): ldap_set_option() on the per-handle LDAP struct is silently discarded once the global TLS context exists
OpenLDAP 2.7.1 was just released. It seems pretty unusual they would change like this. Is there a bug in OpenLDAP or are we using it wrong, etc.
Lines 35 to 44 in 0134682
AFAICS we've got USE_OPENLDAP for recent versions of OpenLDAP. Maybe we should require it for those versions instead of allowing our legacy code to interface with more recent OpenLDAP if that's what's happening? Maybe I don't understand what's going on because I don't know much about building with LDAP except the code comment that I put above.
/cc @MegaManSec
There was a problem hiding this comment.
That's correct, USE_OPENLDAP is set for non-legacy (aka. non-lib/ldap.c,
aka. lib/openldap.c) LDAP builds. For "legacy" LDAP, it is not set.
I think the man pages should ideally not mention internal macros
such as USE_OPENLDAP. It's another case of pre-existing use in
CURLOPT_PINNEDPUBLICKEY.md. Maybe it should be fixed.
We have two LDAP implementations:
- ldap.c -
!USE_OPENLDAP, legacy LDAP, WinLDAP, OpenLDAP/2.4.28/Apple, IBMLDAP - openldap.c -
USE_OPENLDAP, OpenLDAP, OpenLDAP/x.y.z
Version numbers don't make a difference.
The ambiguous one is the Apple case. Perhaps we should
rename it in the version output to 'AppleLDAP/2.4.28' to clarify
and then use "OpenLDAP" for the mainline implementation,
and maybe say "legacy LDAP (WinLDAP, AppleLDAP[, IBMLDAP])"
for the rest?
There was a problem hiding this comment.
I think we need to hear from Joshua so we know what exactly this vulnerability affects like what he means by legacy ldap. Like did he determine that anything that uses ldap.c interface has the problem etc
There was a problem hiding this comment.
I think we need to hear from Joshua so we know what exactly this vulnerability affects like what he means by legacy ldap. Like did he determine that anything that uses ldap.c interface has the problem etc
AFAIK we already knew these information, they just weren't explicitly said
in the documentation. ldap.c uses its own TLS stack, hence the TLS knobs
applying to the TLS backend linked to curl are ineffective when using
that (the legacy) LDAP API.
There was a problem hiding this comment.
Re-reading the commit messages and the documentation text added, I'm
also not sure what it means. When talking about "legacy" LDAP, it talks about
OpenLDAP version, e.g. 2.5. curl's CA bundle is used in legacy LDAP (TIL!)
on non-Windows, which, AFAICS only means Apple (and perhaps IBMLDAP),
and Apple's LDAP keeps reporting its own version as OpenLDAP/2.4.28/Apple
on latest macOS 27:
https://github.com/curl/curl/actions/runs/37688447071/job/113022200048
It's also kind of difficult to document precisely, because CAINFO support
is missing with WinLDAP, present when LDAP_OPT_X_TLS is defined,
which in practice is Apple LDAP (presumably all revisions, but I'd need to
look this up). If it's a process-global or per-handle setting, well, how would
we know this?
a34c064 to
c8f4dc8
Compare
|
Updated the text to address the concerns found so far. |
That looks a lot better. I still think we should hear from @MegaManSec on this to confirm or nail down details. Is his report from HackerOne or where was this reported? If it's from a private report that will eventually become public I think the URL should be included for posterity. |
It is a from a private report, but we cannot easily make that one public because of reasons: Joshua and friends provided us with a huge amount of potential problems in a large collection that we store in a private location. We have no means to publicize details of that and there is no URL for it that will be available long term. (We can of course opt to manually create issues for specific ones if we feel it is needed.) |
|
To Jay's questions, if I've followed properly:
|
| For LDAP, this option is honored when using the OpenLDAP backend, including | ||
| Apple's fork. It is not supported with WinLDAP. |
There was a problem hiding this comment.
Apple's fork doesn't support this, at least on macOS 15.7. Its libldap is built on Secure Transport and rejects LDAP_OPT_X_TLS_CACERTFILE, and ldap.c treats that as fatal, so with verification on an ldaps:// transfer fails with CURLE_SSL_CERTPROBLEM ("ERROR setting PEM CA cert"). I tested it on current master built against Apple's LDAP.framework. The wording from the other three pages fits here too:
| For LDAP, this option is honored when using the OpenLDAP backend, including | |
| Apple's fork. It is not supported with WinLDAP. | |
| For LDAP, this option only has an effect when using the OpenLDAP backend, | |
| which routes TLS through libcurl. It is not supported with Apple's OpenLDAP | |
| fork. |
| For LDAP, this option only has an effect when using the OpenLDAP backend, | ||
| which routes TLS through libcurl. It is not supported with Apple's OpenLDAP | ||
| fork. |
There was a problem hiding this comment.
WinLDAP has supported disabling verification since 8.22.0 (4ce309d), so "only has an effect when using the OpenLDAP backend" is too broad. On Apple's fork, setting this to 0 only turns off libldap's hostname check; the certificate chain is still verified. Suggest:
| For LDAP, this option only has an effect when using the OpenLDAP backend, | |
| which routes TLS through libcurl. It is not supported with Apple's OpenLDAP | |
| fork. | |
| For LDAP with Apple's OpenLDAP fork, the certificate chain is still verified | |
| when this option is disabled. |
On OpenLDAP >= 2.5, the TLS context the legacy LDAP backend's ldaps:// connection actually uses is process-global, not per-handle. Verified empirically (OpenLDAP 2.7.1): ldap_set_option() on the per-handle LDAP struct is silently discarded once the global TLS context exists, so CURLOPT_SSL_VERIFYPEER/CURLOPT_CAINFO do not reliably govern the SDK's TLS verification. Mirroring per-handle options onto the global libldap context was considered but rejected: the global TLS context is built once and cached, so it also leaks across unrelated concurrent or sequential LDAP handles in the same process, which would trade one silent-misverification hazard for another. Document the limitation instead, matching the existing CURLOPT_PINNEDPUBLICKEY note. Reported-by: Joshua Rogers
The legacy LDAP backend hands ldaps:// TLS entirely to the native LDAP SDK. Neither OpenLDAP's LDAP_OPT_X_TLS_* options nor WinLDAP's TLS options expose OCSP-stapling (certificate status) verification, so enabling CURLOPT_SSL_VERIFYSTATUS for an LDAPS transfer is silently unenforced: only CA/chain verification is configured, never stapling. No equivalent SDK facility exists to map this option onto, so document the limitation instead, matching the existing CURLOPT_PINNEDPUBLICKEY, CURLOPT_CAINFO and CURLOPT_SSL_VERIFYPEER notes for the same backend. Reported-by: Joshua Rogers
drop saying about process-global and per-handle in context of legacy LDAP, mention Apple and WinLDAP by name when necessary.
|
Thanks Joshua! Made these updates:
|
0573997 to
08585d3
Compare
There was a problem hiding this comment.
🟢 Approval recommended
The backend descriptions are sound; the remaining WinLDAP option-pairing clarification is minor.
1 open finding
What changed in this PR
This PR clarifies how curl’s TLS options behave across LDAP backends in the libcurl option documentation.
Changes:
- Document backend-specific behavior for CA certificates, peer verification, and certificate status checks.
- Clarify public-key pinning for LDAP without referring to an internal build macro.
| File | Description |
|---|---|
docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md |
Notes which LDAP backend supports status checks. |
docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md |
Describes peer verification across LDAP backends. |
docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md |
Clarifies LDAP pinning support. |
docs/libcurl/opts/CURLOPT_CAINFO.md |
Describes LDAP CA certificate handling. |
🧠 Review effort: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Say how these TLS options behave when using mainline OpenLDAP, Apple's
LDAP fork and WinLDAP.
Also:
USE_OPENLDAPinternal C macro.CURLOPT_PINNEDPUBLICKEYman page with the above.Follow-up to f2692b5 docs: note CURLOPT_PINNEDPUBLICKEY has no effect on legacy LDAP backend #21682
For reference about the two LDAP "tracks" curl supports:
releases reported as
OpenLDAP/2.4.28/Apple, fixed version), IBMLDAP*,use their own TLS-backend, some curl TLS options explicitly supported
build-time-macro/runtime-depending,
!USE_OPENLDAP*: there is almost nothing publicly known about IBMLDAP.
USE_OPENLDAP, mainline OpenLDAP, versioned, usescurl's TLS-backend, reports itself as
OpenLDAP/x.y.z.Reported-by: Joshua Rogers