doc: clarify x509.checkIssued only checks metadata · nodejs/node@0868525

Original file line numberDiff line numberDiff line change

@@ -2651,7 +2651,23 @@ added: v15.6.0

26512651

* `otherCert` {X509Certificate}

26522652

* Returns: {boolean}

26532653
2654-

Checks whether this certificate was issued by the given `otherCert`.

2654+

Checks whether this certificate was potentially issued by the given `otherCert`

2655+

by comparing the certificate metadata.

2656+
2657+

This is useful for pruning a list of possible issuer certificates which have been

2658+

selected using a more rudimentary filtering routine, i.e. just based on subject

2659+

and issuer names.

2660+
2661+

Finally, to verify that this certificate's signature was produced by a private key

2662+

corresponding to `otherCert`'s public key use [`x509.verify(publicKey)`][]

2663+

with `otherCert`'s public key represented as a [`KeyObject`][]

2664+

like so

2665+
2666+

```js

2667+

if (!x509.verify(otherCert.publicKey)) {

2668+

throw new Error('otherCert did not issue x509');

2669+

}

2670+

```

26552671
26562672

### `x509.checkPrivateKey(privateKey)`

26572673

@@ -6205,6 +6221,7 @@ See the [list of SSL OP Flags][] for details.

62056221

[`verify.update()`]: #verifyupdatedata-inputencoding

62066222

[`verify.verify()`]: #verifyverifyobject-signature-signatureencoding

62076223

[`x509.fingerprint256`]: #x509fingerprint256

6224+

[`x509.verify(publicKey)`]: #x509verifypublickey

62086225

[caveats when using strings as inputs to cryptographic APIs]: #using-strings-as-inputs-to-cryptographic-apis

62096226

[certificate object]: tls.md#certificate-object

62106227

[encoding]: buffer.md#buffers-and-character-encodings