doc: document that an empty OPENSSL_CONF skips config loading

[orgads]

OpenSSL is initialized with CONF_MFLAGS_IGNORE_MISSING_FILE, so a missing configuration file does not prevent Node.js from starting.

That flag only covers ENOENT and ENOTDIR though, so a file that exists but cannot be opened is still fatal. Running in a container where /etc/ssl is not accessible to the current user aborts startup with an error that gives no way out:

  OpenSSL configuration error:
  ...:BIO_new_file:Permission denied:...fopen(/etc/ssl/openssl.cnf, rb)

There is a way out: OpenSSL skips config loading entirely when OPENSSL_CONF is set to an empty value. Say so in the error message, along with the options that select a different file, and document the empty value.

Closes: #62230

[nodejs-github-bot]

Review requested:

• @nodejs/startup

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.28%. Comparing base (6c862f4) to head (096ad5b).
⚠️ Report is 235 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #64949      +/-   ##
==========================================
- Coverage   90.29%   90.28%   -0.01%     
==========================================
  Files         759      759              
  Lines      248295   248295              
  Branches    46861    46858       -3     
==========================================
- Hits       224205   224184      -21     
+ Misses      15517    15515       -2     
- Partials     8573     8596      +23     

see 26 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[panva]

I'm not certain hiding an error reading something that may (or may not, i haven't done that due dilligence) be a convention and openssl default is a good idea.

Making the error clearer I'd have no issue with.

[orgads]

I'm not certain hiding an error reading something that may (or may not, i haven't done that due dilligence) be a convention and openssl default is a good idea.

Making the error clearer I'd have no issue with.

CONF_MFLAGS_IGNORE_MISSING_FILE is already set above, so a missing default config is fine. But OpenSSL only honours that flag for ENOENT/ENOTDIR - every other errno becomes BIO_R_SYS_LIB and stays fatal. Absent /etc/ssl/openssl.cnf works; the same file one chmod away kills startup. That asymmetry looks accidental, not deliberate.

The branch only fires when neither OPENSSL_CONF nor --openssl-config was given, i.e. the compiled-in OPENSSLDIR path. Explicit configs and their .includes stay fatal, so the FIPS reasoning above is untouched.

Does that address your concern? If you'd still rather not have it silent, I can print the error to stderr as a warning and continue.

[panva]

Setting OPENSSL_CONF= (empty) already skips config loading without touching the filesystem, so docker run -e OPENSSL_CONF= … works today.

And I don't think the FIPS argument holds — the default openssl.cnf is where .include fipsmodule.cnf usually lives, which is what #38732 made fatal. With this, a FIPS host whose config becomes unreadable would just start without FIPS.

I'd rather keep it fatal and mention OPENSSL_CONF in the error message, plus document that an empty value skips loading.

[orgads]

You're right on both counts - OPENSSL_CONF= short-circuits before the file is opened, and the FIPS .include does live in the default config, so my argument missed the case that matters.

Reworked: the error stays fatal, and now says to point OPENSSL_CONF or --openssl-config=file at another file, or set OPENSSL_CONF= (empty) to start without one. Documented that last bit too. PTAL.

[panva]

I'd drop the src/node.cc change entirely and land this as docs only. The OpenSSL error already names the file and the reason, and the message change fires for every config error, including parse failures where "start without one" is the wrong advice if the file sets up FIPS.

If the variable is set to an empty value, Node.js starts without loading any
OpenSSL configuration file. This is a way past a default configuration file
that exists but cannot be read, for example when `/etc/ssl` is not accessible
to the user Node.js runs as, which is otherwise fatal at startup. No
configuration is applied in that case, including any [FIPS mode][] setup the
file would have performed.

If the [`--openssl-config`][] command-line option is used, the environment
variable is ignored, and an empty value has no effect.

[orgads]

Done. Dropped the src/node.cc change and took your wording verbatim.

I kept the test. It asserts only existing behaviour - unreadable default config is fatal, OPENSSL_CONF= starts - so it pins the escape hatch the docs now promise. Let me know if you'd rather this be strictly docs.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/75610/

[nodejs-github-bot]

Landed in a0c366c