function

tls.checkServerIdentity

hostname: string,
cert: PeerCertificate
): undefined | Error;

Verifies the certificate cert is issued to hostname.

Returns Error object, populating it with reason, host, and cert on failure. On success, returns undefined.

This function is intended to be used in combination with thecheckServerIdentity option that can be passed to connect and as such operates on a certificate object. For other purposes, consider using x509.checkHost() instead.

This function can be overwritten by providing an alternative function as the options.checkServerIdentity option that is passed to tls.connect(). The overwriting function can call tls.checkServerIdentity() of course, to augment the checks done with additional verification.

This function is only called if the certificate passed all other checks, such as being issued by trusted CA (options.ca).

Earlier versions of Node.js incorrectly accepted certificates for a givenhostname if a matching uniformResourceIdentifier subject alternative name was present (see CVE-2021-44531). Applications that wish to acceptuniformResourceIdentifier subject alternative names can use a custom options.checkServerIdentity function that implements the desired behavior.

@param hostname

The host name or IP address to verify the certificate against.

@param cert

A certificate object representing the peer's certificate.

Referenced types

interface PeerCertificate

  • asn1Curve?: string

    The ASN.1 name of the OID of the elliptic curve. Well-known curves are identified by an OID. While it is unusual, it is possible that the curve is identified by its mathematical properties, in which case it will not have an OID.

  • bits?: number

    For RSA keys: The RSA bit size.

    For EC keys: The key size in bits.

  • ca: boolean

    true if a Certificate Authority (CA), false otherwise.

  • exponent?: string

    The RSA exponent, as a string in hexadecimal number notation.

  • ext_key_usage?: string[]

    The extended key usage, a set of OIDs.

  • fingerprint: string

    The SHA-1 digest of the DER encoded certificate. It is returned as a : separated hexadecimal string.

  • fingerprint256: string

    The SHA-256 digest of the DER encoded certificate. It is returned as a : separated hexadecimal string.

  • fingerprint512: string

    The SHA-512 digest of the DER encoded certificate. It is returned as a : separated hexadecimal string.

  • infoAccess?: Dict<string[]>

    An array describing the AuthorityInfoAccess, used with OCSP.

  • issuer: Certificate

    The certificate issuer, described in the same terms as the subject.

  • modulus?: string

    The RSA modulus, as a hexadecimal string.

  • nistCurve?: string

    The NIST name for the elliptic curve, if it has one (not all well-known curves have been assigned names by NIST).

  • pubkey?: NonSharedBuffer

    The public key.

  • raw: NonSharedBuffer

    The DER encoded X.509 certificate data.

  • serialNumber: string

    The certificate serial number, as a hex string.

  • subject: Certificate

    The certificate subject.

  • subjectaltname?: string

    A string containing concatenated names for the subject, an alternative to the subject names.

  • valid_from: string

    The date-time the certificate is valid from.

  • valid_to: string

    The date-time the certificate is valid to.

interface Error