feat(NODE-2939): add new hostname canonicalization opts

src/cmap/auth/gssapi.ts

@@ -12,10 +12,23 @@ import {
 import { Callback, ns } from '../../utils';
 import { AuthContext, AuthProvider } from './auth_provider';
 
+/** @public */
+export const GSSAPICanonicalizationValues = Object.freeze({
+  on: true,
+  off: false,
+  none: 'none',
+  forward: 'forward',
+  forwardAndReverse: 'forwardAndReverse'
+} as const);
+
+/** @public */
+export type GSSAPICanonicalizationValues =
+  typeof GSSAPICanonicalizationValues[keyof typeof GSSAPICanonicalizationValues];
+
 type MechanismProperties = {
   /** @deprecated use `CANONICALIZE_HOST_NAME` instead */
   gssapiCanonicalizeHostName?: boolean;
-  CANONICALIZE_HOST_NAME?: boolean;
+  CANONICALIZE_HOST_NAME?: GSSAPICanonicalizationValues;
   SERVICE_HOST?: string;
   SERVICE_NAME?: string;
   SERVICE_REALM?: string;
@@ -93,7 +106,7 @@ function makeKerberosClient(authContext: AuthContext, callback: Callback<Kerbero
 
   const serviceName = mechanismProperties.SERVICE_NAME ?? 'mongodb';
 
-  performGssapiCanonicalizeHostName(
+  performGSSAPICanonicalizeHostName(
     hostAddress.host,
     mechanismProperties,
     (err?: Error | MongoError, host?: string) => {
@@ -174,19 +187,52 @@ function finalize(
   });
 }
 
-function performGssapiCanonicalizeHostName(
+function performGSSAPICanonicalizeHostName(
   host: string,
   mechanismProperties: MechanismProperties,
   callback: Callback<string>
 ): void {
-  if (!mechanismProperties.CANONICALIZE_HOST_NAME) return callback(undefined, host);
+  const mode = mechanismProperties.CANONICALIZE_HOST_NAME;
+  if (!mode || mode === GSSAPICanonicalizationValues.none) {
+    return callback(undefined, host);
+  }
+
+  // If forward and reverse or true
+  if (
+    mode === GSSAPICanonicalizationValues.on ||
+    mode === GSSAPICanonicalizationValues.forwardAndReverse
+  ) {
+    // Perform the lookup of the ip address.
+    dns.lookup(host, (error, address) => {
+      // No ip found, return the error.
+      if (error) return callback(error);
+
+      // Perform a reverse ptr lookup on the ip address.
+      dns.resolvePtr(address, (err, results) => {
+        // This can error as ptr records may not exist for all ips. In this case
+        // fallback to a cname lookup as dns.lookup() does not return the
+        // cname.
+        if (err) {
+          return resolveCname(host, callback);
+        }
+        // If the ptr did not error but had no results, return the host.
+        callback(undefined, results.length > 0 ? results[0] : host);
+      });
+    });
+  } else {
+    // The case for forward is just to resolve the cname as dns.lookup()
+    // will not return it.
+    resolveCname(host, callback);
+  }
+}
 
+function resolveCname(host: string, callback: Callback<string>): void {
   // Attempt to resolve the host name
   dns.resolveCname(host, (err, r) => {
-    if (err) return callback(err);
+    if (err) return callback(undefined, host);
 
     // Get the first resolve host id
-    if (Array.isArray(r) && r.length > 0) {
+    if (r.length > 0) {
       return callback(undefined, r[0]);
     }
 

src/cmap/auth/mongo_credentials.ts

@@ -2,6 +2,7 @@
 import type { Document } from '../../bson';
 import { MongoAPIError, MongoMissingCredentialsError } from '../../error';
 import { emitWarningOnce } from '../../utils';
+import { GSSAPICanonicalizationValues } from './gssapi';
 import { AUTH_MECHS_AUTH_SRC_EXTERNAL, AuthMechanism } from './providers';
 
 // https://github.com/mongodb/specifications/blob/master/source/auth/auth.rst
@@ -30,7 +31,7 @@ export interface AuthMechanismProperties extends Document {
   SERVICE_HOST?: string;
   SERVICE_NAME?: string;
   SERVICE_REALM?: string;
-  CANONICALIZE_HOST_NAME?: boolean;
+  CANONICALIZE_HOST_NAME?: GSSAPICanonicalizationValues;
   AWS_SESSION_TOKEN?: string;
 }
 
@@ -167,6 +168,11 @@ export class MongoCredentials {
       // TODO(NODE-3485): Replace this with a MongoAuthValidationError
       throw new MongoAPIError(`Password not allowed for mechanism MONGODB-X509`);
     }
+
+    const canonicalization = this.mechanismProperties.CANONICALIZE_HOST_NAME ?? false;
+    if (!Object.values(GSSAPICanonicalizationValues).includes(canonicalization)) {
+      throw new MongoAPIError(`Invalid CANONICALIZE_HOST_NAME value: ${canonicalization}`);
+    }
   }
 
   static merge(

src/index.ts

@@ -86,6 +86,7 @@ export {
 
 // enums
 export { BatchType } from './bulk/common';
+export { GSSAPICanonicalizationValues } from './cmap/auth/gssapi';
 export { AuthMechanism } from './cmap/auth/providers';
 export { Compressor } from './cmap/wire_protocol/compression';
 export { CURSOR_FLAGS } from './cursor/abstract_cursor';

test/manual/kerberos.test.js

@@ -42,6 +42,7 @@ describe('Kerberos', function () {
   }
   let krb5Uri = process.env.MONGODB_URI;
   const parts = krb5Uri.split('@', 2);
+  const host = parts[1].split('/')[0];
 
   if (!process.env.KRB5_PRINCIPAL) {
     console.error('skipping Kerberos tests, KRB5_PRINCIPAL environment variable is not defined');
@@ -79,18 +80,179 @@ describe('Kerberos', function () {
     });
   });
 
-  it('validate that CANONICALIZE_HOST_NAME can be passed in', function (done) {
-    if (process.platform === 'darwin') {
-      this.test.skipReason = 'DNS does not resolve with proper CNAME record on evergreen MacOS';
-      this.skip();
+  context('when passing in CANONICALIZE_HOST_NAME', function () {
+    beforeEach(function () {
+      //if (process.platform === 'darwin') {
+      //  this.currentTest.skipReason =
+      //    'DNS does not resolve with proper CNAME record on evergreen MacOS';
+      //  this.skip();
+      //}
+    });
+
+    for (const option of [true, 'forward']) {
+      context(`when the value is ${option}`, function () {
+        it('authenticates with a forward cname lookup', function (done) {
+          const client = new MongoClient(
+            `${krb5Uri}&authMechanismProperties=SERVICE_NAME:mongodb,CANONICALIZE_HOST_NAME:${option}&maxPoolSize=1`
+          );
+          client.connect(function (err, client) {
+            if (err) return done(err);
+            expect(dns.resolveCname).to.be.calledOnce;
+            verifyKerberosAuthentication(client, done);
+          });
+        });
+      });
     }
-    const client = new MongoClient(
-      `${krb5Uri}&authMechanismProperties=SERVICE_NAME:mongodb,CANONICALIZE_HOST_NAME:true&maxPoolSize=1`
-    );
-    client.connect(function (err, client) {
-      if (err) return done(err);
-      expect(dns.resolveCname).to.be.calledOnce;
-      verifyKerberosAuthentication(client, done);
+
+    for (const option of [false, 'none']) {
+      context(`when the value is ${option}`, function () {
+        it('authenticates with no dns lookups', function (done) {
+          const client = new MongoClient(
+            `${krb5Uri}&authMechanismProperties=SERVICE_NAME:mongodb,CANONICALIZE_HOST_NAME:${option}&maxPoolSize=1`
+          );
+          client.connect(function (err, client) {
+            if (err) return done(err);
+            expect(dns.resolveCname).to.not.be.called;
+            // 2 calls when establishing connection - expect no third call.
+            expect(dns.lookup).to.be.calledTwice;
+            verifyKerberosAuthentication(client, done);
+          });
+        });
+      });
+    }
+
+    context('when the value is forwardAndReverse', function () {
+      context('when the reverse lookup succeeds', function () {
+        const resolveStub = (address, callback) => {
+          callback(null, [host]);
+        };
+
+        beforeEach(function () {
+          dns.resolvePtr.restore();
+          sinon.stub(dns, 'resolvePtr').callsFake(resolveStub);
+        });
+
+        it('authenticates with a forward dns lookup and a reverse ptr lookup', function (done) {
+          const client = new MongoClient(
+            `${krb5Uri}&authMechanismProperties=SERVICE_NAME:mongodb,CANONICALIZE_HOST_NAME:forwardAndReverse&maxPoolSize=1`
+          );
+          client.connect(function (err, client) {
+            if (err) return done(err);
+            // 2 calls to establish connection, 1 call in canonicalization.
+            expect(dns.lookup).to.be.calledThrice;
+            expect(dns.resolvePtr).to.be.calledOnce;
+            verifyKerberosAuthentication(client, done);
+          });
+        });
+      });
+
+      context('when the reverse lookup is empty', function () {
+        const resolveStub = (address, callback) => {
+          callback(null, []);
+        };
+
+        beforeEach(function () {
+          dns.resolvePtr.restore();
+          sinon.stub(dns, 'resolvePtr').callsFake(resolveStub);
+        });
+
+        it('authenticates with a fallback cname lookup', function (done) {
+          const client = new MongoClient(
+            `${krb5Uri}&authMechanismProperties=SERVICE_NAME:mongodb,CANONICALIZE_HOST_NAME:forwardAndReverse&maxPoolSize=1`
+          );
+          client.connect(function (err, client) {
+            if (err) return done(err);
+            // 2 calls to establish connection, 1 call in canonicalization.
+            expect(dns.lookup).to.be.calledThrice;
+            // This fails.
+            expect(dns.resolvePtr).to.be.calledOnce;
+            // Expect the fallback to be called.
+            expect(dns.resolveCname).to.be.calledOnce;
+            verifyKerberosAuthentication(client, done);
+          });
+        });
+      });
+
+      context('when the reverse lookup fails', function () {
+        const resolveStub = (address, callback) => {
+          callback(new Error('not found'), null);
+        };
+
+        beforeEach(function () {
+          dns.resolvePtr.restore();
+          sinon.stub(dns, 'resolvePtr').callsFake(resolveStub);
+        });
+
+        it('authenticates with a fallback cname lookup', function (done) {
+          const client = new MongoClient(
+            `${krb5Uri}&authMechanismProperties=SERVICE_NAME:mongodb,CANONICALIZE_HOST_NAME:forwardAndReverse&maxPoolSize=1`
+          );
+          client.connect(function (err, client) {
+            if (err) return done(err);
+            // 2 calls to establish connection, 1 call in canonicalization.
+            expect(dns.lookup).to.be.calledThrice;
+            // This fails.
+            expect(dns.resolvePtr).to.be.calledOnce;
+            // Expect the fallback to be called.
+            expect(dns.resolveCname).to.be.calledOnce;
+            verifyKerberosAuthentication(client, done);
+          });
+        });
+      });
+
+      context('when the cname lookup fails', function () {
+        const resolveStub = (address, callback) => {
+          callback(new Error('not found'), null);
+        };
+
+        beforeEach(function () {
+          dns.resolvePtr.restore();
+          sinon.stub(dns, 'resolveCname').callsFake(resolveStub);
+        });
+
+        it('authenticates with a fallback host name', function (done) {
+          const client = new MongoClient(
+            `${krb5Uri}&authMechanismProperties=SERVICE_NAME:mongodb,CANONICALIZE_HOST_NAME:forwardAndReverse&maxPoolSize=1`
+          );
+          client.connect(function (err, client) {
+            if (err) return done(err);
+            // 2 calls to establish connection, 1 call in canonicalization.
+            expect(dns.lookup).to.be.calledThrice;
+            // This fails.
+            expect(dns.resolvePtr).to.be.calledOnce;
+            // Expect the fallback to be called.
+            expect(dns.resolveCname).to.be.calledOnce;
+            verifyKerberosAuthentication(client, done);
+          });
+        });
+      });
+
+      context('when the cname lookup is empty', function () {
+        const resolveStub = (address, callback) => {
+          callback(null, []);
+        };
+
+        beforeEach(function () {
+          dns.resolvePtr.restore();
+          sinon.stub(dns, 'resolveCname').callsFake(resolveStub);
+        });
+
+        it('authenticates with a fallback host name', function (done) {
+          const client = new MongoClient(
+            `${krb5Uri}&authMechanismProperties=SERVICE_NAME:mongodb,CANONICALIZE_HOST_NAME:forwardAndReverse&maxPoolSize=1`
+          );
+          client.connect(function (err, client) {
+            if (err) return done(err);
+            // 2 calls to establish connection, 1 call in canonicalization.
+            expect(dns.lookup).to.be.calledThrice;
+            // This fails.
+            expect(dns.resolvePtr).to.be.calledOnce;
+            // Expect the fallback to be called.
+            expect(dns.resolveCname).to.be.calledOnce;
+            verifyKerberosAuthentication(client, done);
+          });
+        });
+      });
     });
   });