Update credentials.js documentation for verify options and add verify options to typescript definition.

packages/grpc-native-core/index.d.ts

@@ -794,6 +794,25 @@ declare module "grpc" {
     ERROR,
   }
 
+  /**
+   * A callback that will receive the expected hostname and presented peer
+   * certificate as parameters. The callback should throw an error to
+   * indicate that the presented certificate is considered invalid.
+   */
+  export type CheckServerIdentityCallback = (hostname: string, cert: string) => void;
+
+  /**
+   * Additional peer verification options that can be set when creating
+   * SSL credentials.
+   */
+  export interface VerifyOptions: {
+    /**
+     * If set, this callback will be invoked after the usual hostname verification
+     * has been performed on the peer certificate.
+     */
+    checkServerIdentity?: CheckServerIdentityCallback;
+  }
+
   /**
    * Credentials module
    *
@@ -828,9 +847,10 @@ declare module "grpc" {
      * @param rootCerts The root certificate data
      * @param privateKey The client certificate private key, if applicable
      * @param certChain The client certificate cert chain, if applicable
+     * @param verifyOptions Additional peer verification options, if desired
      * @return The SSL Credentials object
      */
-    createSsl(rootCerts?: Buffer, privateKey?: Buffer, certChain?: Buffer): ChannelCredentials;
+    createSsl(rootCerts?: Buffer, privateKey?: Buffer, certChain?: Buffer, verifyOptions?: VerifyOptions): ChannelCredentials;
 
     /**
      * Create a gRPC credentials object from a metadata generation function. This

packages/grpc-native-core/src/credentials.js

@@ -78,7 +78,8 @@ var _ = require('lodash');
 
 /**
  * Create an SSL Credentials object. If using a client-side certificate, both
- * the second and third arguments must be passed.
+ * the second and third arguments must be passed. Additional peer verification
+ * options can be passed in the fourth argument as described below.
  * @memberof grpc.credentials
  * @alias grpc.credentials.createSsl
  * @kind function
@@ -86,6 +87,18 @@ var _ = require('lodash');
  * @param {Buffer=} private_key The client certificate private key, if
  *     applicable
  * @param {Buffer=} cert_chain The client certificate cert chain, if applicable
+ * @param {Object} verify_options Additional peer verification options. Can
+ *     be undefined, in which case default behavior is preserved.
+ *     Supported options are: "checkServerIdentity": (servername, cert) => {}
+ *     The callback passed to checkServerIdentity will be invoked when the
+ *     channel is opened in order to provide an opportunity to perform
+ *     additional verification of the peer certificate as passed to the
+ *     callback in the second parameter. The expected hostname is passed as
+ *     the first parameter. If the callback considers the peer certificate
+ *     invalid it should throw an error which will cause the handshake to
+ *     be terminated. Note that supplying this callback does not disable
+ *     the usual hostname verification which will also be performed on the
+ *     certificate before this callback is invoked.
  * @return {grpc.credentials~ChannelCredentials} The SSL Credentials object
  */
 exports.createSsl = ChannelCredentials.createSsl;