crypto: add docs & tests for cert.pubkey & cert.fingerprint256

Include example on how to pin certificate and/or public key

doc/api/https.md

@@ -168,9 +168,10 @@ changes:
 
 Makes a request to a secure web server.
 
-The following additional `options` from [`tls.connect()`][] are also accepted
-when using a custom [`Agent`][]: `ca`, `cert`, `ciphers`, `clientCertEngine`,
-`key`, `passphrase`, `pfx`, `rejectUnauthorized`, `secureProtocol`, `servername`
+Additionally, the `options` from [`tls.connect()`][] are also accepted when
+using a custom [`Agent`][], such as: `ca`, `cert`, `ciphers`,
+`clientCertEngine`, `key`, `passphrase`, `pfx`, `rejectUnauthorized`,
+`secureProtocol`, `servername`.
 
 `options` can be an object, a string, or a [`URL`][] object. If `options` is a
 string, it is automatically parsed with [`url.parse()`][]. If it is a [`URL`][]
@@ -250,6 +251,98 @@ const req = https.request(options, (res) => {
 });
 ```
 
+Example pinning on certificate fingerprint, or the public key (similar to `pin-sha256`):
+
+```js
+const tls = require('tls');
+const https = require('https');
+const crypto = require('crypto');
+
+function sha256(s) {
+  return crypto.createHash('sha256').update(s).digest('base64');
+}
+const options = {
+  hostname: 'github.com',
+  port: 443,
+  path: '/',
+  method: 'GET',
+  checkServerIdentity: function(host, cert) {
+    // Make sure the certificate is issued to the host we are connected to
+    const err = tls.checkServerIdentity(host, cert);
+    if (err) {
+      return err;
+    }
+
+    // Pin the public key, similar to HPKP pin-sha25 pinning
+    const pubkey256 = 'pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=';
+    if (sha256(cert.pubkey) !== pubkey256) {
+      const msg = 'Certificate verification error: ' +
+        `The public key of '${cert.subject.CN}' ` +
+        'does not match our pinned fingerprint';
+      return new Error(msg);
+    }
+
+    // Pin the exact certificate, rather then the pub key
+    const cert256 = '25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:' +
+      'D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16';
+    if (cert.fingerprint256 !== cert256) {
+      const msg = 'Certificate verification error: ' +
+        `The certificate of '${cert.subject.CN}' ` +
+        'does not match our pinned fingerprint';
+      return new Error(msg);
+    }
+
+    // This loop is informational only.
+    // Print the certificate and public key fingerprints of all certs in the
+    // chain. Its common to pin the public key of the issuer on the public
+    // internet, while pinning the public key of the service in sensitive
+    // environments.
+    do {
+      console.log('Subject Common Name:', cert.subject.CN);
+      console.log('  Certificate SHA256 fingerprint:', cert.fingerprint256);
+
+      hash = crypto.createHash('sha256');
+      console.log('  Public key ping-sha256:', sha256(cert.pubkey));
+
+      lastprint256 = cert.fingerprint256;
+      cert = cert.issuerCertificate;
+    } while (cert.fingerprint256 !== lastprint256);
+
+  },
+};
+
+options.agent = new https.Agent(options);
+const req = https.request(options, (res) => {
+  console.log('All OK. Server matched our pinned cert or public key');
+  console.log('statusCode:', res.statusCode);
+  // Print the HPKP values
+  console.log('headers:', res.headers['public-key-pins']);
+
+  res.on('data', (d) => {});
+});
+
+req.on('error', (e) => {
+  console.error(e.message);
+});
+req.end();
+
+```
+ Outputs for example:
+```text
+Subject Common Name: github.com
+  Certificate SHA256 fingerprint: 25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16
+  Public key ping-sha256: pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=
+Subject Common Name: DigiCert SHA2 Extended Validation Server CA
+  Certificate SHA256 fingerprint: 40:3E:06:2A:26:53:05:91:13:28:5B:AF:80:A0:D4:AE:42:2C:84:8C:9F:78:FA:D0:1F:C9:4B:C5:B8:7F:EF:1A
+  Public key ping-sha256: RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho=
+Subject Common Name: DigiCert High Assurance EV Root CA
+  Certificate SHA256 fingerprint: 74:31:E5:F4:C3:C1:CE:46:90:77:4F:0B:61:E0:54:40:88:3B:A9:A0:1E:D0:0B:A6:AB:D7:80:6E:D3:B1:18:CF
+  Public key ping-sha256: WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18=
+All OK. Server matched our pinned cert or public key
+statusCode: 200
+headers: max-age=0; pin-sha256="WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18="; pin-sha256="RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho="; pin-sha256="k2v657xBsOVe1PQRwOsHsw3bsGT2VzIqz5K+59sNQws="; pin-sha256="K87oWBWM9UZfyddvDfoxL+8lpNyoUB2ptGtn0fv6G2Q="; pin-sha256="IQBnNBEiFuhj+8x6X8XLgh01V9Ic5/V3IRQLNFFc7v4="; pin-sha256="iie1VXtL7HzAMF+/PVPR9xzT80kQxdZeJ+zduCB3uj0="; pin-sha256="LvRiGEjRqfzurezaWuj8Wie2gyHMrW5Q06LspMnox7A="; includeSubDomains
+```
+
 [`Agent`]: #https_class_https_agent
 [`URL`]: url.html#url_the_whatwg_url_api
 [`http.Agent`]: http.html#http_class_http_agent

doc/api/tls.md

@@ -619,9 +619,11 @@ For example:
   issuerCertificate:
    { ... another certificate, possibly with a .issuerCertificate ... },
   raw: < RAW DER buffer >,
+  pubkey: < RAW DER buffer >,
   valid_from: 'Nov 11 09:52:22 2009 GMT',
   valid_to: 'Nov  6 09:52:22 2029 GMT',
   fingerprint: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF',
+  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',
   serialNumber: 'B9B0D332A1AA5635' }
 ```
 
@@ -786,12 +788,14 @@ The cert object contains the parsed certificate and will have a structure simila
      '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 ....> }
+  raw: <Buffer ... > }
 ```
 
 ## tls.connect(options[, callback])

test/parallel/test-tls-peer-certificate.js

@@ -20,15 +20,23 @@
 // USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 'use strict';
-require('../common');
+const common = require('../common');
 const fixtures = require('../common/fixtures');
+if (!common.hasCrypto) {
+  common.skip('missing crypto');
+}
+const crypto = require('crypto');
 
 // Verify that detailed getPeerCertificate() return value has all certs.
 
 const {
   assert, connect, debug, keys
 } = require(fixtures.path('tls-connect'));
 
+function sha256(s) {
+  return crypto.createHash('sha256').update(s);
+}
+
 connect({
   client: { rejectUnauthorized: false },
   server: keys.agent1,
@@ -49,6 +57,24 @@ connect({
     peerCert.fingerprint,
     '8D:06:3A:B3:E5:8B:85:29:72:4F:7D:1B:54:CD:95:19:3C:EF:6F:AA'
   );
+  assert.strictEqual(
+    peerCert.fingerprint256,
+    'A1:DC:01:1A:EC:A3:7B:86:A8:C2:3E:26:9F:EB:EE:5C:A9:3B:BE:06' +
+    ':4C:A4:00:53:93:A9:66:07:A7:BC:13:32'
+  );
+
+  // SHA256 fingerprint of the public key
+  assert.strictEqual(
+    sha256(peerCert.pubkey).digest('hex'),
+    'fa5152e4407bad1e7537ef5bfc3f19fa9a62ee04432fd75e109b1803704c31ba'
+  );
+
+  // HPKP / RFC7469 "pin-sha256" of the public key
+  assert.strictEqual(
+    sha256(peerCert.pubkey).digest('base64'),
+    '+lFS5EB7rR51N+9b/D8Z+ppi7gRDL9deEJsYA3BMMbo='
+  );
+
   assert.deepStrictEqual(peerCert.infoAccess['OCSP - URI'],
                          [ 'http://ocsp.nodejs.org/' ]);