Skip to content

docs: note CAINFO/SSL_VERIFYPEER/SSL_VERIFYSTATUS effect on LDAP - #23303

Closed
vszakats wants to merge 9 commits into
curl:masterfrom
vszakats:docs-ldap-legacy-more
Closed

vszakats wants to merge 9 commits into
curl:masterfrom
vszakats:docs-ldap-legacy-more

Conversation

@vszakats

@vszakats vszakats commented Oct 7, 2026 •

Copy link
Copy Markdown
Member

Say how these TLS options behave when using mainline OpenLDAP, Apple's
LDAP fork and WinLDAP.

Also:

For reference about the two LDAP "tracks" curl supports:

  • lib/ldap.c: "legacy" LDAP, WinLDAP, Apple's OpenLDAP fork (existing
    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.
  • lib/openssl.c: USE_OPENLDAP, mainline OpenLDAP, versioned, uses
    curl's TLS-backend, reports itself as OpenLDAP/x.y.z.

Reported-by: Joshua Rogers

@vszakats vszakats changed the title docs: note CAINFO/SSL_VERIFYPEER have no effect on legacy LDAP backend docs: note CAINFO/SSL_VERIFYPEER/SSL_VERIFYSTATUS have no effect on legacy LDAP backend Oct 7, 2026
Comment thread docs/libcurl/opts/CURLOPT_CAINFO.md Outdated

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. "legacy LDAP" is not a good term in user documentation as nobody will know who uses that...

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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).

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

curl/lib/ldap.c

Lines 35 to 44 in 0134682

/*
* Notice that USE_OPENLDAP is only a source code selection switch. When
* libcurl is built with USE_OPENLDAP defined the libcurl source code that
* gets compiled is the code from openldap.c, otherwise the code that gets
* compiled is the code from ldap.c.
*
* When USE_OPENLDAP is defined a recent version of the OpenLDAP library
* might be required for compilation and runtime. In order to use ancient
* OpenLDAP library versions, USE_OPENLDAP shall not be defined.
*/

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

@vszakats vszakats Oct 7, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@vszakats vszakats Oct 8, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@vszakats vszakats Oct 8, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

@vszakats
vszakats force-pushed the docs-ldap-legacy-more branch from a34c064 to c8f4dc8 Compare October 8, 2026 01:19
@vszakats vszakats changed the title docs: note CAINFO/SSL_VERIFYPEER/SSL_VERIFYSTATUS have no effect on legacy LDAP backend docs: note CAINFO/SSL_VERIFYPEER/SSL_VERIFYSTATUS effect on LDAP backends Oct 8, 2026
@vszakats vszakats changed the title docs: note CAINFO/SSL_VERIFYPEER/SSL_VERIFYSTATUS effect on LDAP backends docs: note CAINFO/SSL_VERIFYPEER/SSL_VERIFYSTATUS effect on LDAP Oct 8, 2026
@vszakats

vszakats commented Oct 8, 2026

Copy link
Copy Markdown
Member Author

Updated the text to address the concerns found so far.

@jay

jay commented Oct 8, 2026

Copy link
Copy Markdown
Member

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.

@bagder

bagder commented Oct 8, 2026 •

Copy link
Copy Markdown
Member

If it's from a private report that will eventually become public

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.)

@MegaManSec

Copy link
Copy Markdown
Contributor

To Jay's questions, if I've followed properly:

  1. This isn't new in OpenLDAP. libldap only applies per-handle TLS options when the handle gets its own context (LDAP_OPT_X_TLS_NEWCTX); otherwise it uses the process-wide default. That's the same in 2.4.28, current master and Apple's fork, so it's just ldap.c that needs adjusting.
  2. Builds already pick openldap.c whenever ldap_init_fd exists, so ldap.c isn't used with mainline OpenLDAP. In practice ldap.c means Apple's fork and WinLDAP.

Comment thread docs/libcurl/opts/CURLOPT_CAINFO.md Outdated
Comment on lines +58 to +59
For LDAP, this option is honored when using the OpenLDAP backend, including
Apple's fork. It is not supported with WinLDAP.

@MegaManSec MegaManSec Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Suggested change
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.

Comment on lines +72 to +74
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.

@MegaManSec MegaManSec Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Suggested change
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.

MegaManSec and others added 9 commits October 9, 2026 10:03
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.
@vszakats

vszakats commented Oct 9, 2026 •

Copy link
Copy Markdown
Member Author

Thanks Joshua!

Made these updates:

  • CURLOPT_CAINFO: mention WinLDAP using the system CA store.
  • CURLOPT_CAINFO: delete the exception for Apple's OpenLDAP fork.
  • say CURLOPT_SSL_VERIFYPEER is supported by WinLDAP,
    also say version 8.22.0.
  • say CURLOPT_SSL_VERIFYPEER is not supported by Apple's OpenLDAP fork.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 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.

@vszakats vszakats closed this in 70c084a Oct 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Development

Successfully merging this pull request may close these issues.

5 participants