diff --git a/doc/api/crypto.md b/doc/api/crypto.md index eb7fa2a01602f8..c73cb1894d174f 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -2651,7 +2651,23 @@ added: v15.6.0 * `otherCert` {X509Certificate} * Returns: {boolean} -Checks whether this certificate was issued by the given `otherCert`. +Checks whether this certificate was potentially issued by the given `otherCert` +by comparing the certificate metadata. + +This is useful for pruning a list of possible issuer certificates which have been +selected using a more rudimentary filtering routine, i.e. just based on subject +and issuer names. + +Finally, to verify that this certificate's signature was produced by a private key +corresponding to `otherCert`'s public key use [`x509.verify(publicKey)`][] +with `otherCert`'s public key represented as a [`KeyObject`][] +like so + +```js +if (!x509.verify(otherCert.publicKey)) { + throw new Error('otherCert did not issue x509'); +} +``` ### `x509.checkPrivateKey(privateKey)` @@ -6205,6 +6221,7 @@ See the [list of SSL OP Flags][] for details. [`verify.update()`]: #verifyupdatedata-inputencoding [`verify.verify()`]: #verifyverifyobject-signature-signatureencoding [`x509.fingerprint256`]: #x509fingerprint256 +[`x509.verify(publicKey)`]: #x509verifypublickey [caveats when using strings as inputs to cryptographic APIs]: #using-strings-as-inputs-to-cryptographic-apis [certificate object]: tls.md#certificate-object [encoding]: buffer.md#buffers-and-character-encodings