@@ -2967,6 +2967,11 @@ be passed instead of a public key.
29672967
29682968<!-- YAML
29692969added: v15.6.0
2970+ changes:
2971+ - version: REPLACEME
2972+ pr-url: https://github.com/nodejs/node/pull/67408
2973+ description: Required field conversion, certificate encoding, fingerprint
2974+ calculation, and AIA or EKU decoding failures now throw.
29702975-->
29712976
29722977Encapsulates an X509 certificate and provides read-only access to
@@ -3144,6 +3149,10 @@ if (!x509.verify(otherCert.publicKey)) {
31443149
31453150<!-- YAML
31463151added: v15.6.0
3152+ changes:
3153+ - version: REPLACEME
3154+ pr-url: https://github.com/nodejs/node/pull/67408
3155+ description: Unsupported key comparisons and comparison errors now throw.
31473156-->
31483157
31493158* ` privateKey ` {KeyObject} A private key.
@@ -3152,6 +3161,10 @@ added: v15.6.0
31523161Checks whether the public key for this certificate is consistent with
31533162the given private key.
31543163
3164+ Returns ` false ` if the keys do not match. Throws
3165+ ` ERR_CRYPTO_UNSUPPORTED_OPERATION ` if the keys cannot be compared,
3166+ or ` ERR_CRYPTO_OPERATION_FAILED ` if the comparison cannot be completed.
3167+
31553168### ` x509.extensions `
31563169
31573170<!-- YAML
@@ -3203,6 +3216,8 @@ added: v15.6.0
32033216
32043217The SHA-1 fingerprint of this certificate.
32053218
3219+ Throws if the fingerprint cannot be calculated.
3220+
32063221Because SHA-1 is cryptographically broken and because the security of SHA-1 is
32073222significantly worse than that of algorithms that are commonly used to sign
32083223certificates, consider using [ ` x509.fingerprint256 ` ] [ ] instead.
@@ -3217,6 +3232,8 @@ added: v15.6.0
32173232
32183233The SHA-256 fingerprint of this certificate.
32193234
3235+ Throws if the fingerprint cannot be calculated.
3236+
32203237### ` x509.fingerprint512 `
32213238
32223239<!-- YAML
@@ -3229,6 +3246,8 @@ added:
32293246
32303247The SHA-512 fingerprint of this certificate.
32313248
3249+ Throws if the fingerprint cannot be calculated.
3250+
32323251Because computing the SHA-256 fingerprint is usually faster and because it is
32333252only half the size of the SHA-512 fingerprint, [ ` x509.fingerprint256 ` ] [ ] may be
32343253a better choice. While SHA-512 presumably provides a higher level of security in
@@ -3248,10 +3267,11 @@ changes:
32483267 in response to CVE-2021-44532.
32493268-->
32503269
3251- * Type: {string}
3270+ * Type: {string|undefined }
32523271
32533272A textual representation of the certificate's authority information access
3254- extension.
3273+ extension, or ` undefined ` if the extension is absent. Throws if the extension
3274+ cannot be decoded or formatted.
32553275
32563276This is a line feed separated list of access descriptions. Each line begins with
32573277the access method and the kind of the access location, followed by a colon and
@@ -3273,6 +3293,8 @@ added: v15.6.0
32733293
32743294The issuer identification included in this certificate.
32753295
3296+ Throws if the issuer name cannot be formatted.
3297+
32763298### ` x509.issuerCertificate `
32773299
32783300<!-- YAML
@@ -3330,9 +3352,10 @@ issuer name cannot be inspected.
33303352added: v15.6.0
33313353-->
33323354
3333- * Type: {string\[ ] }
3355+ * Type: {string\[ ] |undefined }
33343356
3335- An array detailing the key extended usages for this certificate.
3357+ An array of extended key usage OIDs, or ` undefined ` if the extension is absent.
3358+ Throws if the extension cannot be decoded or an OID cannot be formatted.
33363359
33373360### ` x509.publicKey `
33383361
@@ -3354,6 +3377,8 @@ added: v15.6.0
33543377
33553378A ` Buffer ` containing the DER encoding of this certificate.
33563379
3380+ Throws if the certificate cannot be encoded.
3381+
33573382### ` x509.serialNumber `
33583383
33593384<!-- YAML
@@ -3364,6 +3389,8 @@ added: v15.6.0
33643389
33653390The serial number of this certificate.
33663391
3392+ Throws if the serial number cannot be formatted.
3393+
33673394Serial numbers are assigned by certificate authorities and do not uniquely
33683395identify certificates. Consider using [ ` x509.fingerprint256 ` ] [ ] as a unique
33693396identifier instead.
@@ -3378,6 +3405,8 @@ added: v15.6.0
33783405
33793406The complete subject of this certificate.
33803407
3408+ Throws if the subject name cannot be formatted.
3409+
33813410### ` x509.subjectAltName `
33823411
33833412<!-- YAML
@@ -3486,6 +3515,8 @@ There is no standard JSON encoding for X509 certificates. The
34863515` toJSON() ` method returns a string containing the PEM encoded
34873516certificate.
34883517
3518+ Throws if the certificate cannot be encoded.
3519+
34893520### ` x509.toLegacyObject() `
34903521
34913522<!-- YAML
@@ -3497,6 +3528,15 @@ added: v15.6.0
34973528Returns information about this certificate using the legacy
34983529[ certificate object] [ ] encoding.
34993530
3531+ Throws if a required field conversion, Authority Information Access or Extended
3532+ Key Usage decoding, fingerprint calculation, or certificate encoding fails.
3533+ Optional public key fields may be omitted as described in the legacy encoding.
3534+
3535+ The TLS methods [ ` tlsSocket.getPeerCertificate() ` ] [ ] and
3536+ [ ` tlsSocket.getCertificate() ` ] [ ] use the legacy conversion behavior:
3537+ unconvertible AIA and EKU extensions are omitted, and invalid validity times
3538+ are returned as ` 'Bad time value' ` .
3539+
35003540### ` x509.toString() `
35013541
35023542<!-- YAML
@@ -3507,6 +3547,8 @@ added: v15.6.0
35073547
35083548Returns the PEM-encoded certificate.
35093549
3550+ Throws if the certificate cannot be encoded.
3551+
35103552### ` x509.validFrom `
35113553
35123554<!-- YAML
@@ -3517,8 +3559,7 @@ added: v15.6.0
35173559
35183560The date/time from which this certificate is valid.
35193561
3520- If the certificate's ` notBefore ` time cannot be parsed, this is the string
3521- ` 'Bad time value' ` .
3562+ Throws if the time cannot be converted or formatted.
35223563
35233564### ` x509.validFromDate `
35243565
@@ -3532,15 +3573,7 @@ added:
35323573
35333574The date/time from which this certificate is valid, encapsulated in a ` Date ` object.
35343575
3535- If the certificate's ` notBefore ` time cannot be parsed, this property is an
3536- invalid ` Date ` whose ` getTime() ` method returns ` NaN ` .
3537-
3538- Relational comparisons with an invalid ` Date ` evaluate to ` false ` . To check
3539- whether the current time is within the certificate's validity period, use
3540- ` now >= x509.validFromDate && now <= x509.validToDate ` . This expression
3541- evaluates to ` false ` if either date is invalid. Checking
3542- ` now < x509.validFromDate || now > x509.validToDate ` instead can fail to
3543- reject certificates with invalid dates.
3576+ Throws if the time cannot be converted.
35443577
35453578### ` x509.validTo `
35463579
@@ -3552,8 +3585,7 @@ added: v15.6.0
35523585
35533586The date/time until which this certificate is valid.
35543587
3555- If the certificate's ` notAfter ` time cannot be parsed, this is the string
3556- ` 'Bad time value' ` .
3588+ Throws if the time cannot be converted or formatted.
35573589
35583590### ` x509.validToDate `
35593591
@@ -3567,15 +3599,7 @@ added:
35673599
35683600The date/time until which this certificate is valid, encapsulated in a ` Date ` object.
35693601
3570- If the certificate's ` notAfter ` time cannot be parsed, this property is an
3571- invalid ` Date ` whose ` getTime() ` method returns ` NaN ` .
3572-
3573- Relational comparisons with an invalid ` Date ` evaluate to ` false ` . To check
3574- whether the current time is within the certificate's validity period, use
3575- ` now >= x509.validFromDate && now <= x509.validToDate ` . This expression
3576- evaluates to ` false ` if either date is invalid. Checking
3577- ` now < x509.validFromDate || now > x509.validToDate ` instead can fail to
3578- reject certificates with invalid dates.
3602+ Throws if the time cannot be converted.
35793603
35803604### ` x509.signature `
35813605
@@ -3641,6 +3665,8 @@ added: v24.9.0
36413665
36423666The OID of the algorithm used to sign the certificate.
36433667
3668+ Throws if the OID cannot be formatted.
3669+
36443670### ` x509.version `
36453671
36463672<!-- YAML
@@ -3656,6 +3682,10 @@ v3. A certificate with no encoded version field has version `1`.
36563682
36573683<!-- YAML
36583684added: v15.6.0
3685+ changes:
3686+ - version: REPLACEME
3687+ pr-url: https://github.com/nodejs/node/pull/67408
3688+ description: Errors reported separately from verification failure now throw.
36593689-->
36603690
36613691* ` publicKey ` {KeyObject} A public key.
@@ -3664,6 +3694,11 @@ added: v15.6.0
36643694Verifies that this certificate was signed by the given public key.
36653695Does not perform any other validation checks on the certificate.
36663696
3697+ Returns ` true ` for a valid signature and ` false ` for a verification failure or
3698+ an incompatible key type. A signature BIT STRING with invalid unused bits also
3699+ returns ` false ` . Throws for other errors reported separately from verification
3700+ failure.
3701+
36673702## ` node:crypto ` module methods and properties
36683703
36693704### ` crypto.argon2(algorithm, parameters, callback) `
@@ -8118,6 +8153,8 @@ See the [list of SSL OP Flags][] for details.
81188153[ `stream.Transform` ] : stream.md#class-streamtransform
81198154[ `stream.Writable` options ] : stream.md#new-streamwritableoptions
81208155[ `stream.transform` options ] : stream.md#new-streamtransformoptions
8156+ [ `tlsSocket.getCertificate()` ] : tls.md#tlssocketgetcertificate
8157+ [ `tlsSocket.getPeerCertificate()` ] : tls.md#tlssocketgetpeercertificatedetailed
81218158[ `util.promisify()` ] : util.md#utilpromisifyoriginal
81228159[ `verify.update()` ] : #verifyupdatedata-inputencoding
81238160[ `verify.verify()` ] : #verifyverifykey-signature-signatureencoding
0 commit comments