doc: describe certificate object properties
PR-URL: https://github.com/nodejs/node/pull/24358 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: Tobias Nießen <tniessen@tnie.de>
This commit is contained in:
Sam Roberts
parent
08c14d98cd
commit
a856406c2d
128
doc/api/tls.md
128
doc/api/tls.md
@ -638,44 +638,84 @@ added: v0.11.4
|
|||||||
|
|
||||||
* `detailed` {boolean} Include the full certificate chain if `true`, otherwise
|
* `detailed` {boolean} Include the full certificate chain if `true`, otherwise
|
||||||
include just the peer's certificate.
|
include just the peer's certificate.
|
||||||
* Returns: {Object}
|
* Returns: {Object} A certificate object.
|
||||||
|
|
||||||
Returns an object representing the peer's certificate. The returned object has
|
Returns an object representing the peer's certificate. If the peer does not
|
||||||
some properties corresponding to the fields of the certificate.
|
provide a certificate, an empty object will be returned. If the socket has been
|
||||||
|
destroyed, `null` will be returned.
|
||||||
|
|
||||||
If the full certificate chain was requested, each certificate will include an
|
If the full certificate chain was requested, each certificate will include an
|
||||||
`issuerCertificate` property containing an object representing its issuer's
|
`issuerCertificate` property containing an object representing its issuer's
|
||||||
certificate.
|
certificate.
|
||||||
|
|
||||||
|
#### Certificate Object
|
||||||
|
|
||||||
|
A certificate object has properties corresponding to the fields of the
|
||||||
|
certificate.
|
||||||
|
|
||||||
|
* `raw` {Buffer} The DER encoded X.509 certificate data.
|
||||||
|
* `subject` {Object} The certificate subject, described in terms of
|
||||||
|
Country (`C:`), StateOrProvince (`ST`), Locality (`L`), Organization (`O`),
|
||||||
|
OrganizationalUnit (`OU`), and CommonName (`CN`). The CommonName is typically
|
||||||
|
a DNS name with TLS certificates. Example:
|
||||||
|
`{C: 'UK', ST: 'BC', L: 'Metro', O: 'Node Fans', OU: 'Docs', CN: 'example.com'}`.
|
||||||
|
* `issuer` {Object} The certificate issuer, described in the same terms as the
|
||||||
|
`subject`.
|
||||||
|
* `valid_from` {string} The date-time the certificate is valid from.
|
||||||
|
* `valid_to` {string} The date-time the certificate is valid to.
|
||||||
|
* `serialNumber` {string} The certificate serial number, as a hex string.
|
||||||
|
Example: `'B9B0D332A1AA5635'`.
|
||||||
|
* `fingerprint` {string} The SHA-1 digest of the DER encoded certificate. It is
|
||||||
|
returned as a `:` separated hexadecimal string. Example: `'2A:7A:C2:DD:...'`.
|
||||||
|
* `fingerprint256` {string} The SHA-256 digest of the DER encoded certificate.
|
||||||
|
It is returned as a `:` separated hexadecimal string. Example:
|
||||||
|
`'2A:7A:C2:DD:...'`.
|
||||||
|
* `ext_key_usage` {Array} (Optional) The extended key usage, a set of OIDs.
|
||||||
|
* `subjectaltname` {Array} (Optional) An array of names for the subject, an
|
||||||
|
alternative to the `subject` names.
|
||||||
|
* `infoAccess` {Array} (Optional) An array describing the AuthorityInfoAccess,
|
||||||
|
used with OCSP.
|
||||||
|
* `issuerCert` {Object} (Optional) The issuer certificate object. For
|
||||||
|
self-signed certificates, this may be a circular reference.
|
||||||
|
|
||||||
|
The certificate may contain information about the public key, depending on
|
||||||
|
the key type.
|
||||||
|
|
||||||
|
For RSA keys, the following properties may be defined:
|
||||||
|
* `exponent` {string} The RSA exponent, as a string in hexadecimal number
|
||||||
|
notation. Example: `'0x010001'`.
|
||||||
|
* `modulus` {string} The RSA modulus, as a hexadecimal string. Example:
|
||||||
|
`'B56CE45CB7...'`.
|
||||||
|
* `pubkey` {Buffer} The public key.
|
||||||
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
{ subject:
|
{ subject:
|
||||||
{ C: 'UK',
|
{ OU: [ 'Domain Control Validated', 'PositiveSSL Wildcard' ],
|
||||||
ST: 'Acknack Ltd',
|
CN: '*.nodejs.org' },
|
||||||
L: 'Rhys Jones',
|
|
||||||
O: 'node.js',
|
|
||||||
OU: 'Test TLS Certificate',
|
|
||||||
CN: 'localhost' },
|
|
||||||
issuer:
|
issuer:
|
||||||
{ C: 'UK',
|
{ C: 'GB',
|
||||||
ST: 'Acknack Ltd',
|
ST: 'Greater Manchester',
|
||||||
L: 'Rhys Jones',
|
L: 'Salford',
|
||||||
O: 'node.js',
|
O: 'COMODO CA Limited',
|
||||||
OU: 'Test TLS Certificate',
|
CN: 'COMODO RSA Domain Validation Secure Server CA' },
|
||||||
CN: 'localhost' },
|
subjectaltname: 'DNS:*.nodejs.org, DNS:nodejs.org',
|
||||||
issuerCertificate:
|
infoAccess:
|
||||||
{ ... another certificate, possibly with an .issuerCertificate ... },
|
{ 'CA Issuers - URI':
|
||||||
raw: < RAW DER buffer >,
|
[ 'http://crt.comodoca.com/COMODORSADomainValidationSecureServerCA.crt' ],
|
||||||
pubkey: < RAW DER buffer >,
|
'OCSP - URI': [ 'http://ocsp.comodoca.com' ] },
|
||||||
valid_from: 'Nov 11 09:52:22 2009 GMT',
|
modulus: 'B56CE45CB740B09A13F64AC543B712FF9EE8E4C284B542A1708A27E82A8D151CA178153E12E6DDA15BF70FFD96CB8A88618641BDFCCA03527E665B70D779C8A349A6F88FD4EF6557180BD4C98192872BCFE3AF56E863C09DDD8BC1EC58DF9D94F914F0369102B2870BECFA1348A0838C9C49BD1C20124B442477572347047506B1FCD658A80D0C44BCC16BC5C5496CFE6E4A8428EF654CD3D8972BF6E5BFAD59C93006830B5EB1056BBB38B53D1464FA6E02BFDF2FF66CD949486F0775EC43034EC2602AEFBF1703AD221DAA2A88353C3B6A688EFE8387811F645CEED7B3FE46E1F8B9F59FAD028F349B9BC14211D5830994D055EEA3D547911E07A0ADDEB8A82B9188E58720D95CD478EEC9AF1F17BE8141BE80906F1A339445A7EB5B285F68039B0F294598A7D1C0005FC22B5271B0752F58CCDEF8C8FD856FB7AE21C80B8A2CE983AE94046E53EDE4CB89F42502D31B5360771C01C80155918637490550E3F555E2EE75CC8C636DDE3633CFEDD62E91BF0F7688273694EEEBA20C2FC9F14A2A435517BC1D7373922463409AB603295CEB0BB53787A334C9CA3CA8B30005C5A62FC0715083462E00719A8FA3ED0A9828C3871360A73F8B04A4FC1E71302844E9BB9940B77E745C9D91F226D71AFCAD4B113AAF68D92B24DDB4A2136B55A1CD1ADF39605B63CB639038ED0F4C987689866743A68769CC55847E4A06D6E2E3F1',
|
||||||
valid_to: 'Nov 6 09:52:22 2029 GMT',
|
exponent: '0x10001',
|
||||||
fingerprint: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF',
|
pubkey: <Buffer ... >,
|
||||||
fingerprint256: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF:00:11:22:33:44:55:66:77:88:99:AA:BB',
|
valid_from: 'Aug 14 00:00:00 2017 GMT',
|
||||||
serialNumber: 'B9B0D332A1AA5635' }
|
valid_to: 'Nov 20 23:59:59 2019 GMT',
|
||||||
|
fingerprint: '01:02:59:D9:C3:D2:0D:08:F7:82:4E:44:A4:B4:53:C5:E2:3A:87:4D',
|
||||||
|
fingerprint256: '69:AE:1A:6A:D4:3D:C6:C1:1B:EA:C6:23:DE:BA:2A:14:62:62:93:5C:7A:EA:06:41:9B:0B:BC:87:CE:48:4E:02',
|
||||||
|
ext_key_usage: [ '1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2' ],
|
||||||
|
serialNumber: '66593D57F20CBC573E433381B5FEC280',
|
||||||
|
raw: <Buffer ... > }
|
||||||
```
|
```
|
||||||
|
|
||||||
If the peer does not provide a certificate, an empty object will be returned.
|
|
||||||
If the socket has been destroyed, `null` will be returned.
|
|
||||||
|
|
||||||
### tlsSocket.getPeerFinished()
|
### tlsSocket.getPeerFinished()
|
||||||
<!-- YAML
|
<!-- YAML
|
||||||
added: v9.9.0
|
added: v9.9.0
|
||||||
@ -830,8 +870,7 @@ added: v0.8.4
|
|||||||
|
|
||||||
* `hostname` {string} The host name or IP address to verify the certificate
|
* `hostname` {string} The host name or IP address to verify the certificate
|
||||||
against.
|
against.
|
||||||
* `cert` {Object} An object representing the peer's certificate. The returned
|
* `cert` {Object} A [certificate object][] representing the peer's certificate.
|
||||||
object has some properties corresponding to the fields of the certificate.
|
|
||||||
* Returns: {Error|undefined}
|
* Returns: {Error|undefined}
|
||||||
|
|
||||||
Verifies the certificate `cert` is issued to `hostname`.
|
Verifies the certificate `cert` is issued to `hostname`.
|
||||||
@ -847,36 +886,6 @@ the checks done with additional verification.
|
|||||||
This function is only called if the certificate passed all other checks, such as
|
This function is only called if the certificate passed all other checks, such as
|
||||||
being issued by trusted CA (`options.ca`).
|
being issued by trusted CA (`options.ca`).
|
||||||
|
|
||||||
The cert object contains the parsed certificate and will have a structure
|
|
||||||
similar to:
|
|
||||||
|
|
||||||
```text
|
|
||||||
{ subject:
|
|
||||||
{ OU: [ 'Domain Control Validated', 'PositiveSSL Wildcard' ],
|
|
||||||
CN: '*.nodejs.org' },
|
|
||||||
issuer:
|
|
||||||
{ C: 'GB',
|
|
||||||
ST: 'Greater Manchester',
|
|
||||||
L: 'Salford',
|
|
||||||
O: 'COMODO CA Limited',
|
|
||||||
CN: 'COMODO RSA Domain Validation Secure Server CA' },
|
|
||||||
subjectaltname: 'DNS:*.nodejs.org, DNS:nodejs.org',
|
|
||||||
infoAccess:
|
|
||||||
{ 'CA Issuers - URI':
|
|
||||||
[ 'http://crt.comodoca.com/COMODORSADomainValidationSecureServerCA.crt' ],
|
|
||||||
'OCSP - URI': [ 'http://ocsp.comodoca.com' ] },
|
|
||||||
modulus: 'B56CE45CB740B09A13F64AC543B712FF9EE8E4C284B542A1708A27E82A8D151CA178153E12E6DDA15BF70FFD96CB8A88618641BDFCCA03527E665B70D779C8A349A6F88FD4EF6557180BD4C98192872BCFE3AF56E863C09DDD8BC1EC58DF9D94F914F0369102B2870BECFA1348A0838C9C49BD1C20124B442477572347047506B1FCD658A80D0C44BCC16BC5C5496CFE6E4A8428EF654CD3D8972BF6E5BFAD59C93006830B5EB1056BBB38B53D1464FA6E02BFDF2FF66CD949486F0775EC43034EC2602AEFBF1703AD221DAA2A88353C3B6A688EFE8387811F645CEED7B3FE46E1F8B9F59FAD028F349B9BC14211D5830994D055EEA3D547911E07A0ADDEB8A82B9188E58720D95CD478EEC9AF1F17BE8141BE80906F1A339445A7EB5B285F68039B0F294598A7D1C0005FC22B5271B0752F58CCDEF8C8FD856FB7AE21C80B8A2CE983AE94046E53EDE4CB89F42502D31B5360771C01C80155918637490550E3F555E2EE75CC8C636DDE3633CFEDD62E91BF0F7688273694EEEBA20C2FC9F14A2A435517BC1D7373922463409AB603295CEB0BB53787A334C9CA3CA8B30005C5A62FC0715083462E00719A8FA3ED0A9828C3871360A73F8B04A4FC1E71302844E9BB9940B77E745C9D91F226D71AFCAD4B113AAF68D92B24DDB4A2136B55A1CD1ADF39605B63CB639038ED0F4C987689866743A68769CC55847E4A06D6E2E3F1',
|
|
||||||
exponent: '0x10001',
|
|
||||||
pubkey: <Buffer ... >,
|
|
||||||
valid_from: 'Aug 14 00:00:00 2017 GMT',
|
|
||||||
valid_to: 'Nov 20 23:59:59 2019 GMT',
|
|
||||||
fingerprint: '01:02:59:D9:C3:D2:0D:08:F7:82:4E:44:A4:B4:53:C5:E2:3A:87:4D',
|
|
||||||
fingerprint256: '69:AE:1A:6A:D4:3D:C6:C1:1B:EA:C6:23:DE:BA:2A:14:62:62:93:5C:7A:EA:06:41:9B:0B:BC:87:CE:48:4E:02',
|
|
||||||
ext_key_usage: [ '1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2' ],
|
|
||||||
serialNumber: '66593D57F20CBC573E433381B5FEC280',
|
|
||||||
raw: <Buffer ... > }
|
|
||||||
```
|
|
||||||
|
|
||||||
## tls.connect(options[, callback])
|
## tls.connect(options[, callback])
|
||||||
<!-- YAML
|
<!-- YAML
|
||||||
added: v0.11.3
|
added: v0.11.3
|
||||||
@ -1402,5 +1411,6 @@ where `secureSocket` has the same API as `pair.cleartext`.
|
|||||||
[TLS Session Tickets]: https://www.ietf.org/rfc/rfc5077.txt
|
[TLS Session Tickets]: https://www.ietf.org/rfc/rfc5077.txt
|
||||||
[TLS recommendations]: https://wiki.mozilla.org/Security/Server_Side_TLS
|
[TLS recommendations]: https://wiki.mozilla.org/Security/Server_Side_TLS
|
||||||
[asn1.js]: https://www.npmjs.com/package/asn1.js
|
[asn1.js]: https://www.npmjs.com/package/asn1.js
|
||||||
|
[certificate object]: #tls_certificate_object
|
||||||
[modifying the default cipher suite]: #tls_modifying_the_default_tls_cipher_suite
|
[modifying the default cipher suite]: #tls_modifying_the_default_tls_cipher_suite
|
||||||
[specific attacks affecting larger AES key sizes]: https://www.schneier.com/blog/archives/2009/07/another_new_aes.html
|
[specific attacks affecting larger AES key sizes]: https://www.schneier.com/blog/archives/2009/07/another_new_aes.html
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user