feat(ext/net): extract TLS key and certificate from interfaces (#23327)

Relands #23325

1 files changed, 107 insertions, 32 deletions

diff --git a/ext/net/lib.deno_net.d.ts b/ext/net/lib.deno_net.d.ts
index 597b3d348..4b88b154a 100644
--- a/ext/net/lib.deno_net.d.ts
+++ b/ext/net/lib.deno_net.d.ts
@@ -197,12 +197,50 @@ declare namespace Deno {
     options: UnixListenOptions & { transport: "unix" },
   ): UnixListener;
 
-  /** @category Network */
-  export interface ListenTlsOptions extends TcpListenOptions {
-    /** Server private key in PEM format */
-    key?: string;
-    /** Cert chain in PEM format */
-    cert?: string;
+  /** Provides TLS certified keys, ie: a key that has been certified by a trusted certificate authority.
+   * A certified key generally consists of a private key and certificate part.
+   *
+   * @category Network
+   */
+  export type TlsCertifiedKeyOptions =
+    | TlsCertifiedKeyPem
+    | TlsCertifiedKeyFromFile
+    | TlsCertifiedKeyConnectTls;
+
+  /**
+   * Provides certified key material from strings. The key material is provided in
+   * `PEM`-format (Privacy Enhanced Mail, https://www.rfc-editor.org/rfc/rfc1422) which can be identified by having
+   * `-----BEGIN-----` and `-----END-----` markers at the beginning and end of the strings. This type of key is not compatible
+   * with `DER`-format keys which are binary.
+   *
+   * Deno supports RSA, EC, and PKCS8-format keys.
+   *
+   * ```ts
+   * const key = {
+   *  key: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
+   *  cert: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n" }
+   * };
+   * ```
+   *
+   * @category Network
+   */
+  export interface TlsCertifiedKeyPem {
+    /** The format of this key material, which must be PEM. */
+    keyFormat?: "pem";
+    /** Private key in `PEM` format. RSA, EC, and PKCS8-format keys are supported. */
+    key: string;
+    /** Certificate chain in `PEM` format. */
+    cert: string;
+  }
+
+  /**
+   * @deprecated This will be removed in Deno 2.0. See the
+   * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
+   * for migration instructions.
+   *
+   * @category Network
+   */
+  export interface TlsCertifiedKeyFromFile {
     /** Path to a file containing a PEM formatted CA certificate. Requires
      * `--allow-read`.
      *
@@ -211,16 +249,45 @@ declare namespace Deno {
      * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
      * for migration instructions.
      */
-    certFile?: string;
-    /** Server private key file. Requires `--allow-read`.
+    certFile: string;
+    /** Path to a file containing a private key file. Requires `--allow-read`.
      *
      * @tags allow-read
      * @deprecated This will be removed in Deno 2.0. See the
      * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
      * for migration instructions.
      */
-    keyFile?: string;
+    keyFile: string;
+  }
 
+  /**
+   * @deprecated This will be removed in Deno 2.0. See the
+   * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
+   * for migration instructions.
+   *
+   * @category Network
+   */
+  export interface TlsCertifiedKeyConnectTls {
+    /**
+     * Certificate chain in `PEM` format.
+     *
+     * @deprecated This will be removed in Deno 2.0. See the
+     * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
+     * for migration instructions.
+     */
+    certChain: string;
+    /**
+     * Private key in `PEM` format. RSA, EC, and PKCS8-format keys are supported.
+     *
+     * @deprecated This will be removed in Deno 2.0. See the
+     * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
+     * for migration instructions.
+     */
+    privateKey: string;
+  }
+
+  /** @category Network */
+  export interface ListenTlsOptions extends TcpListenOptions {
     transport?: "tcp";
 
     /** Application-Layer Protocol Negotiation (ALPN) protocols to announce to
@@ -246,7 +313,9 @@ declare namespace Deno {
    * @tags allow-net
    * @category Network
    */
-  export function listenTls(options: ListenTlsOptions): TlsListener;
+  export function listenTls(
+    options: ListenTlsOptions & TlsCertifiedKeyOptions,
+  ): TlsListener;
 
   /** @category Network */
   export interface ConnectOptions {
@@ -343,9 +412,11 @@ declare namespace Deno {
      *
      * @default {"127.0.0.1"} */
     hostname?: string;
-    /**
-     * Server certificate file.
+    /** Path to a file containing a PEM formatted list of root certificates that will
+     * be used in addition to the default root certificates to verify the peer's certificate. Requires
+     * `--allow-read`.
      *
+     * @tags allow-read
      * @deprecated This will be removed in Deno 2.0. See the
      * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
      * for migration instructions.
@@ -361,26 +432,6 @@ declare namespace Deno {
      * TLS handshake.
      */
     alpnProtocols?: string[];
-    /**
-     * PEM formatted client certificate chain.
-     *
-     * @deprecated This will be removed in Deno 2.0. See the
-     * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
-     * for migration instructions.
-     */
-    certChain?: string;
-    /**
-     * PEM formatted (RSA or PKCS8) private key of client certificate.
-     *
-     * @deprecated This will be removed in Deno 2.0. See the
-     * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
-     * for migration instructions.
-     */
-    privateKey?: string;
-    /** Server private key in PEM format. */
-    key?: string;
-    /** Cert chain in PEM format. */
-    cert?: string;
   }
 
   /** Establishes a secure connection over TLS (transport layer security) using
@@ -403,6 +454,30 @@ declare namespace Deno {
    */
   export function connectTls(options: ConnectTlsOptions): Promise<TlsConn>;
 
+  /** Establishes a secure connection over TLS (transport layer security) using
+   * an optional cert file, client certificate, hostname (default is "127.0.0.1") and
+   * port.  The cert file is optional and if not included Mozilla's root certificates will
+   * be used (see also https://github.com/ctz/webpki-roots for specifics)
+   *
+   * ```ts
+   * const caCert = await Deno.readTextFile("./certs/my_custom_root_CA.pem");
+   * const key = "----BEGIN PRIVATE KEY----...";
+   * const cert = "----BEGIN CERTIFICATE----...";
+   * const conn1 = await Deno.connectTls({ port: 80, key, cert });
+   * const conn2 = await Deno.connectTls({ caCerts: [caCert], hostname: "192.0.2.1", port: 80, key, cert });
+   * const conn3 = await Deno.connectTls({ hostname: "[2001:db8::1]", port: 80, key, cert });
+   * const conn4 = await Deno.connectTls({ caCerts: [caCert], hostname: "golang.org", port: 80, key, cert });
+   * ```
+   *
+   * Requires `allow-net` permission.
+   *
+   * @tags allow-net
+   * @category Network
+   */
+  export function connectTls(
+    options: ConnectTlsOptions & TlsCertifiedKeyOptions,
+  ): Promise<TlsConn>;
+
   /** @category Network */
   export interface StartTlsOptions {
     /** A literal IP address or host name that can be resolved to an IP address.