Support CA fingerprint validation

docs/basic-config.asciidoc

@@ -255,6 +255,10 @@ const client = new Client({
 |`boolean`, `'proto'`, `'constructor'` - By the default the client will protect you against prototype poisoning attacks. Read https://web.archive.org/web/20200319091159/https://hueniverse.com/square-brackets-are-the-enemy-ff5b9fd8a3e8?gi=184a27ee2a08[this article] to learn more. If needed you can disable prototype poisoning protection entirely or one of the two checks. Read the `secure-json-parse` https://github.com/fastify/secure-json-parse[documentation] to learn more. +
 _Default:_ `false`
 
+|`caFingerprint`
+|`string` - If configured, verify the supplied CA certificate fingerprint. +
+_Default:_ `null`
+
 |===
 
 [discrete]
@@ -276,4 +280,3 @@ const client = new Client({
   disablePrototypePoisoningProtection: true
 })
 ----
-

docs/connecting.asciidoc

@@ -176,6 +176,28 @@ const client = new Client({
 })
 ----
 
+[discrete]
+[[auth-ca-fingerprint]]
+==== CA fingerprint
+
+To improve the security of your connection to Elasticsearch, you can provide
+a `caFingerprint` option, which will verify the supplied certificate authority fingerprint.
+
+[source,js]
+----
+const { Client } = require('@elastic/elasticsearch')
+const client = new Client({
+  node: 'https://example.com'
+  auth: { ... },
+  // the fingerprint (SHA256) of the CA certificate that is used to sign the certificate that the Elasticsearch node presents for TLS.
+  caFingerprint: '20:0D:CA:FA:76:...',
+  ssl: {
+    // might be required if it's a self-signed certificate
+    rejectUnauthorized: false
+  }
+})
+----
+
 
 [discrete]
 [[client-usage]]

index.d.ts

@@ -118,6 +118,7 @@ interface ClientOptions {
     password?: string;
   };
   disablePrototypePoisoningProtection?: boolean | 'proto' | 'constructor';
+  caFingerprint?: string;
 }
 
 declare class Client {

index.js

@@ -102,6 +102,7 @@ class Client extends ESAPI {
         suggestCompression: false,
         compression: false,
         ssl: null,
+        caFingerprint: null,
         agent: null,
         headers: {},
         nodeFilter: null,
@@ -116,6 +117,10 @@ class Client extends ESAPI {
         disablePrototypePoisoningProtection: false
       }, opts)
 
+    if (options.caFingerprint !== null && isHttpConnection(opts.node || opts.nodes)) {
+      throw new ConfigurationError('You can\'t configure the caFingerprint with a http connection')
+    }
+
     if (process.env.ELASTIC_CLIENT_APIVERSIONING === 'true') {
       options.headers = Object.assign({ accept: 'application/vnd.elasticsearch+json; compatible-with=7' }, options.headers)
     }
@@ -146,6 +151,7 @@ class Client extends ESAPI {
         Connection: options.Connection,
         auth: options.auth,
         emit: this[kEventEmitter].emit.bind(this[kEventEmitter]),
+        caFingerprint: options.caFingerprint,
         sniffEnabled: options.sniffInterval !== false ||
                       options.sniffOnStart !== false ||
                       options.sniffOnConnectionFault !== false
@@ -315,6 +321,19 @@ function getAuth (node) {
   }
 }
 
+function isHttpConnection (node) {
+  if (Array.isArray(node)) {
+    for (const n of node) {
+      if (new URL(n).protocol === 'http:') {
+        return true
+      }
+    }
+    return false
+  } else {
+    return new URL(node).protocol === 'http:'
+  }
+}
+
 const events = {
   RESPONSE: 'response',
   REQUEST: 'request',

lib/Connection.d.ts

@@ -40,6 +40,7 @@ export interface ConnectionOptions {
   roles?: ConnectionRoles;
   auth?: BasicAuth | ApiKeyAuth;
   proxy?: string | URL;
+  caFingerprint?: string;
 }
 
 interface ConnectionRoles {

lib/Connection.js

@@ -42,6 +42,7 @@ class Connection {
     this.headers = prepareHeaders(opts.headers, opts.auth)
     this.deadCount = 0
     this.resurrectTimeout = 0
+    this.caFingerprint = opts.caFingerprint
 
     this._openRequests = 0
     this._status = opts.status || Connection.statuses.ALIVE
@@ -123,10 +124,28 @@ class Connection {
       callback(new RequestAbortedError(), null)
     }
 
+    const onSocket = socket => {
+      /* istanbul ignore else */
+      if (!socket.isSessionReused()) {
+        socket.once('secureConnect', () => {
+          // Check if fingerprint matches
+          /* istanbul ignore else */
+          if (this.caFingerprint !== getIssuerCertificate(socket).fingerprint256) {
+            onError(new Error('Fingerprint does not match'))
+            request.once('error', () => {}) // we need to catch the request aborted error
+            return request.abort()
+          }
+        })
+      }
+    }
+
     request.on('response', onResponse)
     request.on('timeout', onTimeout)
     request.on('error', onError)
     request.on('abort', onAbort)
+    if (this.caFingerprint != null) {
+      request.on('socket', onSocket)
+    }
 
     // Disables the Nagle algorithm
     request.setNoDelay(true)
@@ -152,6 +171,7 @@ class Connection {
       request.removeListener('timeout', onTimeout)
       request.removeListener('error', onError)
       request.removeListener('abort', onAbort)
+      request.removeListener('socket', onSocket)
       cleanedListeners = true
     }
   }
@@ -340,5 +360,24 @@ function prepareHeaders (headers = {}, auth) {
   return headers
 }
 
+function getIssuerCertificate (socket) {
+  let certificate = socket.getPeerCertificate(true)
+  while (certificate && Object.keys(certificate).length > 0) {
+    /* istanbul ignore else */
+    if (certificate.issuerCertificate !== undefined) {
+      // For self-signed certificates, `issuerCertificate` may be a circular reference.
+      /* istanbul ignore else */
+      if (certificate.fingerprint256 === certificate.issuerCertificate.fingerprint256) {
+        break
+      }
+      /* istanbul ignore next */
+      certificate = certificate.issuerCertificate
+    } else {
+      break
+    }
+  }
+  return certificate
+}
+
 module.exports = Connection
 module.exports.internals = { prepareHeaders }

lib/pool/BaseConnectionPool.js

@@ -36,6 +36,7 @@ class BaseConnectionPool {
     this._ssl = opts.ssl
     this._agent = opts.agent
     this._proxy = opts.proxy || null
+    this._caFingerprint = opts.caFingerprint || null
   }
 
   getConnection () {
@@ -72,6 +73,8 @@ class BaseConnectionPool {
     if (opts.agent == null) opts.agent = this._agent
     /* istanbul ignore else */
     if (opts.proxy == null) opts.proxy = this._proxy
+    /* istanbul ignore else */
+    if (opts.caFingerprint == null) opts.caFingerprint = this._caFingerprint
 
     const connection = new this.Connection(opts)
 

lib/pool/index.d.ts

@@ -31,6 +31,7 @@ interface BaseConnectionPoolOptions {
   auth?: BasicAuth | ApiKeyAuth;
   emit: (event: string | symbol, ...args: any[]) => boolean;
   Connection: typeof Connection;
+  caFingerprint?: string;
 }
 
 interface ConnectionPoolOptions extends BaseConnectionPoolOptions {

test/acceptance/sniff.test.js

@@ -77,6 +77,7 @@ test('Should update the connection pool', t => {
           t.same(hosts[i], {
             url: new URL(nodes[id].url),
             id: id,
+            caFingerprint: null,
             roles: {
               master: true,
               data: true,

test/unit/client.test.js

@@ -26,6 +26,7 @@ const intoStream = require('into-stream')
 const { ConnectionPool, Transport, Connection, errors } = require('../../index')
 const { CloudConnectionPool } = require('../../lib/pool')
 const { Client, buildServer } = require('../utils')
+
 let clientVersion = require('../../package.json').version
 if (clientVersion.includes('-')) {
   clientVersion = clientVersion.slice(0, clientVersion.indexOf('-')) + 'p'
@@ -1498,3 +1499,88 @@ test('Bearer auth', t => {
     })
   })
 })
+
+test('Check server fingerprint (success)', t => {
+  t.plan(1)
+
+  function handler (req, res) {
+    res.end('ok')
+  }
+
+  buildServer(handler, { secure: true }, ({ port, caFingerprint }, server) => {
+    const client = new Client({
+      node: `https://localhost:${port}`,
+      caFingerprint
+    })
+
+    client.info((err, res) => {
+      t.error(err)
+      server.stop()
+    })
+  })
+})
+
+test('Check server fingerprint (failure)', t => {
+  t.plan(2)
+
+  function handler (req, res) {
+    res.end('ok')
+  }
+
+  buildServer(handler, { secure: true }, ({ port }, server) => {
+    const client = new Client({
+      node: `https://localhost:${port}`,
+      caFingerprint: 'FO:OB:AR'
+    })
+
+    client.info((err, res) => {
+      t.ok(err instanceof errors.ConnectionError)
+      t.equal(err.message, 'Fingerprint does not match')
+      server.stop()
+    })
+  })
+})
+
+test('caFingerprint can\'t be configured over http / 1', t => {
+  t.plan(2)
+
+  try {
+    new Client({ // eslint-disable-line
+      node: 'http://localhost:9200',
+      caFingerprint: 'FO:OB:AR'
+    })
+    t.fail('shuld throw')
+  } catch (err) {
+    t.ok(err instanceof errors.ConfigurationError)
+    t.equal(err.message, 'You can\'t configure the caFingerprint with a http connection')
+  }
+})
+
+test('caFingerprint can\'t be configured over http / 2', t => {
+  t.plan(2)
+
+  try {
+    new Client({ // eslint-disable-line
+      nodes: ['http://localhost:9200'],
+      caFingerprint: 'FO:OB:AR'
+    })
+    t.fail('shuld throw')
+  } catch (err) {
+    t.ok(err instanceof errors.ConfigurationError)
+    t.equal(err.message, 'You can\'t configure the caFingerprint with a http connection')
+  }
+})
+
+test('caFingerprint can\'t be configured over http / 3', t => {
+  t.plan(1)
+
+  try {
+    new Client({ // eslint-disable-line
+      nodes: ['https://localhost:9200'],
+      caFingerprint: 'FO:OB:AR'
+    })
+    t.pass('should not throw')
+  } catch (err) {
+    t.fail('shuld not throw')
+  }
+})

test/unit/connection.test.js

@@ -28,7 +28,7 @@ const hpagent = require('hpagent')
 const intoStream = require('into-stream')
 const { buildServer } = require('../utils')
 const Connection = require('../../lib/Connection')
-const { TimeoutError, ConfigurationError, RequestAbortedError } = require('../../lib/errors')
+const { TimeoutError, ConfigurationError, RequestAbortedError, ConnectionError } = require('../../lib/errors')
 
 test('Basic (http)', t => {
   t.plan(4)
@@ -947,3 +947,58 @@ test('Abort with a slow body', t => {
 
   setImmediate(() => request.abort())
 })
+
+test('Check server fingerprint (success)', t => {
+  t.plan(2)
+
+  function handler (req, res) {
+    res.end('ok')
+  }
+
+  buildServer(handler, { secure: true }, ({ port, caFingerprint }, server) => {
+    const connection = new Connection({
+      url: new URL(`https://localhost:${port}`),
+      caFingerprint
+    })
+
+    connection.request({
+      path: '/hello',
+      method: 'GET'
+    }, (err, res) => {
+      t.error(err)
+
+      let payload = ''
+      res.setEncoding('utf8')
+      res.on('data', chunk => { payload += chunk })
+      res.on('error', err => t.fail(err))
+      res.on('end', () => {
+        t.equal(payload, 'ok')
+        server.stop()
+      })
+    })
+  })
+})
+
+test('Check server fingerprint (failure)', t => {
+  t.plan(2)
+
+  function handler (req, res) {
+    res.end('ok')
+  }
+
+  buildServer(handler, { secure: true }, ({ port }, server) => {
+    const connection = new Connection({
+      url: new URL(`https://localhost:${port}`),
+      caFingerprint: 'FO:OB:AR'
+    })
+
+    connection.request({
+      path: '/hello',
+      method: 'GET'
+    }, (err, res) => {
+      t.ok(err instanceof ConnectionError)
+      t.equal(err.message, 'Fingerprint does not match')
+      server.stop()
+    })
+  })
+})