doc: UNABLE_TO_VERIFY_LEAF_SIGNATURE/unable to verify the first certificate error not documented

[j3lamp]

📗 API Reference Docs Problem

• Version: v12.17.0
• Platform: macOS 10.14.6 Mojave: Darwin Kernel Version 18.7.0 x86_64
• Subsystem:

Location

HTTPS Module

Affected URL(s):

• https://nodejs.org/api/https://nodejs.org/api/https.html

Problem description

The error "unable to verify the first certificate" with code UNABLE_TO_VERIFY_LEAF_SIGNATURE is not documented making it extremely difficult to fix.

Turns out this was caused by a site not providing a certificate chain. While the error wasn't node's fault the lack of documentation made it look like a bug in node and made fixing the problem extremely difficult.

The true cause was obscured by work configuring certificate stores to explicitly trust the intermediate certificates so web browsers produced no errors. The vast majority of search results suggest disabling security (a terrible idea), the rest point out the NODE_EXTRA_CA_CERTS which is helpful, but I was already using it.

Note: While this isn't actually a security vulnerability the fact that most advice is to turn off certificate verification it can lead people to introduce security vulnerabilities on their own.

Error: unable to verify the first certificate
    at TLSSocket.onConnectSecure (_tls_wrap.js:1496:34)
    at TLSSocket.emit (events.js:315:20)
    at TLSSocket._finishInit (_tls_wrap.js:938:8)
    at TLSWrap.ssl.onhandshakedone (_tls_wrap.js:696:12) {
  code: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'
}

---

• I would like to work on this issue and submit a pull request.

[sam-github]

The cause of this is the server is, incorrectly, not returning the intermediate certificates, its a server configuration problem.

If the server is node, https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options describes how to set a cert chain:

Each cert chain should consist of the PEM formatted certificate for a provided private key, followed by the PEM formatted intermediate certificates (if any), in order, and not including the root CA (the root CA must be pre-known to the peer, see ca).

https://levelup.gitconnected.com/how-to-resolve-certificate-errors-in-nodejs-app-involving-ssl-calls-781ce48daded looks like a decent description of the situation.

A complete tutorial on diagnosing problems with TLS setup, such as the above, would be a deal of work, but worthwhile.

[j3lamp]

I concur. Once I figured that out the problem was easy to fix. What I hoped to find in Node's docs was a list of errors with descriptions as to what they meant. If there had been an entry for UNABLE_TO_VERIFY_LEAF_SIGNATURE that contained your first sentence that would help a lot of people solve what is currently a difficult problem to solve.

A complete tutorial would be awesome, but I don't think that is a necessary place to begin.

Obviously I don't know where to find a list of possible errors. (-: But if I am pointed in the correct directions I can probably dig up some time to try and write something useful.

[DerekNonGeneric]

Obviously I don't know where to find a list of possible errors.

https://nodejs.org/api/errors.html#errors_node_js_error_codes

@j3lamp, is this what you are looking for?

[j3lamp]

It looks like it! The questions now is what errors besides UNABLE_TO_VERIFY_LEAF_SIGNATURE need to be added to it: which, for TLS, seems to be answered here:

node/src/node_crypto_common.cc

Line 297 in 830ef81

const char* X509ErrorCode(long err) { // NOLINT(runtime/int)

Now I know what to dig for probably in OpenSSL. Thank you.

[j3lamp]

I have been thinking about this. Not being a Node.js developer and not having needed to read all of its documentation(!) I am uncertain if these doc should contain OpenSSL errors. On one hand it would be extremely helpful to people who encounter them and would almost certainly make web searches like "node.js error UNABLE_TO_VERIFY_LEAF_SIGNATURE" produce useful results on the first page. On the other hand these aren't Node.js' errors so why should Node.js have to document them and keep them up to date as OpenSSL changes?

I think I have found enough that I can add these errors to Node.js' docs, but I don't believe I can decide if they should be added.

[atulrawat85]

One line solution, https://learninghub.guru blogs article resolved my issue, please refer Link

Their Fantastic Blog's Android App:
Link

[j3lamp]

The suggestion linked to above will work, however if you use rejectUnauthorized: false then certificates won't be verified. It is much better to use NODE_EXTRA_CA_CERTS environment variable to add the other root certificates that should be trusted.