diff --git a/cli/tsc/dts/lib.deno.ns.d.ts b/cli/tsc/dts/lib.deno.ns.d.ts index 80c9851840..cc73efbf90 100644 --- a/cli/tsc/dts/lib.deno.ns.d.ts +++ b/cli/tsc/dts/lib.deno.ns.d.ts @@ -6281,13 +6281,7 @@ declare namespace Deno { * * @category HTTP Server */ - export interface ServeTlsOptions extends ServeOptions { - /** Server private key in PEM format */ - cert: string; - - /** Cert chain in PEM format */ - key: string; - } + export type ServeTlsOptions = ServeOptions & TlsCertifiedKeyOptions; /** * @category HTTP Server diff --git a/cli/tsc/dts/lib.deno.unstable.d.ts b/cli/tsc/dts/lib.deno.unstable.d.ts index 056d8e6099..ae3f60d283 100644 --- a/cli/tsc/dts/lib.deno.unstable.d.ts +++ b/cli/tsc/dts/lib.deno.unstable.d.ts @@ -882,10 +882,6 @@ declare namespace Deno { caCerts?: string[]; /** A HTTP proxy to use for new connections. */ proxy?: Proxy; - /** Cert chain in PEM format. */ - cert?: string; - /** Server private key in PEM format. */ - key?: string; /** Sets the maximum numer of idle connections per host allowed in the pool. */ poolMaxIdlePerHost?: number; /** Set an optional timeout for idle sockets being kept-alive. @@ -962,6 +958,27 @@ declare namespace Deno { options: CreateHttpClientOptions, ): HttpClient; + /** **UNSTABLE**: New API, yet to be vetted. + * + * Create a custom HttpClient to use with {@linkcode fetch}. This is an + * extension of the web platform Fetch API which allows Deno to use custom + * TLS certificates and connect via a proxy while using `fetch()`. + * + * @example ```ts + * const caCert = await Deno.readTextFile("./ca.pem"); + * // Load a client key and certificate that we'll use to connect + * const key = await Deno.readTextFile("./key.key"); + * const cert = await Deno.readTextFile("./cert.crt"); + * const client = Deno.createHttpClient({ caCerts: [ caCert ], key, cert }); + * const response = await fetch("https://myserver.com", { client }); + * ``` + * + * @category Fetch API + */ + export function createHttpClient( + options: CreateHttpClientOptions & TlsCertifiedKeyOptions, + ): HttpClient; + /** **UNSTABLE**: New API, yet to be vetted. * * Represents membership of a IPv4 multicast group. diff --git a/ext/fetch/22_http_client.js b/ext/fetch/22_http_client.js index e1389bbe1f..061a3dda89 100644 --- a/ext/fetch/22_http_client.js +++ b/ext/fetch/22_http_client.js @@ -25,12 +25,7 @@ const { ObjectDefineProperty } = primordials; */ function createHttpClient(options) { options.caCerts ??= []; - const keyPair = loadTlsKeyPair( - options.cert, - undefined, - options.key, - undefined, - ); + const keyPair = loadTlsKeyPair("Deno.createHttpClient", options); return new HttpClient( op_fetch_custom_client( options, diff --git a/ext/net/02_tls.js b/ext/net/02_tls.js index 8d43e8604f..003c5336a7 100644 --- a/ext/net/02_tls.js +++ b/ext/net/02_tls.js @@ -51,54 +51,46 @@ async function connectTls({ port, hostname = "127.0.0.1", transport = "tcp", - certFile = undefined, caCerts = [], - certChain = undefined, - privateKey = undefined, - cert = undefined, - key = undefined, alpnProtocols = undefined, + keyFormat = undefined, + cert = undefined, + certFile = undefined, + certChain = undefined, + key = undefined, + keyFile = undefined, + privateKey = undefined, }) { - if (certFile !== undefined) { - internals.warnOnDeprecatedApi( - "Deno.ConnectTlsOptions.certFile", - new Error().stack, - "Pass the cert file contents to the `Deno.ConnectTlsOptions.cert` option instead.", - ); - } - if (certChain !== undefined) { - internals.warnOnDeprecatedApi( - "Deno.ConnectTlsOptions.certChain", - new Error().stack, - "Use the `Deno.ConnectTlsOptions.cert` option instead.", - ); - } - if (privateKey !== undefined) { - internals.warnOnDeprecatedApi( - "Deno.ConnectTlsOptions.privateKey", - new Error().stack, - "Use the `Deno.ConnectTlsOptions.key` option instead.", - ); - } if (transport !== "tcp") { throw new TypeError(`Unsupported transport: '${transport}'`); } - if (certChain !== undefined && cert !== undefined) { - throw new TypeError( - "Cannot specify both `certChain` and `cert`", + let deprecatedCertFile = undefined; + + // Deno.connectTls has an irregular option where you can just pass `certFile` and + // not `keyFile`. In this case it's used for `caCerts` rather than the client key. + if (certFile !== undefined && keyFile === undefined) { + internals.warnOnDeprecatedApi( + "Deno.ConnectTlsOptions.certFile", + new Error().stack, + "Pass the cert file's contents to the `Deno.ConnectTlsOptions.caCerts` option instead.", ); + + deprecatedCertFile = certFile; + certFile = undefined; } - if (privateKey !== undefined && key !== undefined) { - throw new TypeError( - "Cannot specify both `privateKey` and `key`", - ); - } - cert ??= certChain; - key ??= privateKey; - const keyPair = loadTlsKeyPair(cert, undefined, key, undefined); + + const keyPair = loadTlsKeyPair("Deno.connectTls", { + keyFormat, + cert, + certFile, + certChain, + key, + keyFile, + privateKey, + }); const { 0: rid, 1: localAddr, 2: remoteAddr } = await op_net_connect_tls( { hostname, port }, - { certFile, caCerts, cert, key, alpnProtocols }, + { certFile: deprecatedCertFile, caCerts, alpnProtocols }, keyPair, ); localAddr.transport = "tcp"; @@ -137,29 +129,96 @@ class TlsListener extends Listener { } } +/** + * Returns true if this object has the shape of one of the certified key material + * interfaces. + */ function hasTlsKeyPairOptions(options) { return (ReflectHas(options, "cert") || ReflectHas(options, "key") || ReflectHas(options, "certFile") || - ReflectHas(options, "keyFile")); + ReflectHas(options, "keyFile") || ReflectHas(options, "privateKey") || + ReflectHas(options, "certChain")); } -function loadTlsKeyPair( +/** + * Loads a TLS keypair from one of the various options. If no key material is provided, + * returns a special Null keypair. + */ +function loadTlsKeyPair(api, { + keyFormat, cert, certFile, + certChain, key, keyFile, -) { - if ((certFile !== undefined) ^ (keyFile !== undefined)) { - throw new TypeError( - "If certFile is specified, keyFile must also be specified", - ); - } - if ((cert !== undefined) ^ (key !== undefined)) { - throw new TypeError("If cert is specified, key must also be specified"); + privateKey, +}) { + // Check for "pem" format + if (keyFormat !== undefined && keyFormat !== "pem") { + throw new TypeError('If `keyFormat` is specified, it must be "pem"'); } + function exclusive(a1, a1v, a2, a2v) { + if (a1v !== undefined && a2v !== undefined) { + throw new TypeError( + `Cannot specify both \`${a1}\` and \`${a2}\` for \`${api}\`.`, + ); + } + } + + // Ensure that only one pair is valid + exclusive("certChain", certChain, "cert", cert); + exclusive("certChain", certChain, "certFile", certFile); + exclusive("key", key, "keyFile", keyFile); + exclusive("key", key, "privateKey", privateKey); + + function both(a1, a1v, a2, a2v) { + if (a1v !== undefined && a2v === undefined) { + throw new TypeError( + `If \`${a1}\` is specified, \`${a2}\` must be specified as well for \`${api}\`.`, + ); + } + if (a1v === undefined && a2v !== undefined) { + throw new TypeError( + `If \`${a2}\` is specified, \`${a1}\` must be specified as well for \`${api}\`.`, + ); + } + } + + // Pick one pair of cert/key, certFile/keyFile or certChain/privateKey + both("cert", cert, "key", key); + both("certFile", certFile, "keyFile", keyFile); + both("certChain", certChain, "privateKey", privateKey); + if (certFile !== undefined) { - return op_tls_key_static_from_file("Deno.listenTls", certFile, keyFile); + internals.warnOnDeprecatedApi( + "Deno.TlsCertifiedKeyOptions.keyFile", + new Error().stack, + "Pass the key file's contents to the `Deno.TlsCertifiedKeyPem.key` option instead.", + ); + internals.warnOnDeprecatedApi( + "Deno.TlsCertifiedKeyOptions.certFile", + new Error().stack, + "Pass the cert file's contents to the `Deno.TlsCertifiedKeyPem.cert` option instead.", + ); + return op_tls_key_static_from_file(api, certFile, keyFile); + } else if (certChain !== undefined) { + if (api !== "Deno.connectTls") { + throw new TypeError( + `Invalid options 'certChain' and 'privateKey' for ${api}`, + ); + } + internals.warnOnDeprecatedApi( + "Deno.TlsCertifiedKeyOptions.privateKey", + new Error().stack, + "Use the `Deno.TlsCertifiedKeyPem.key` option instead.", + ); + internals.warnOnDeprecatedApi( + "Deno.TlsCertifiedKeyOptions.certChain", + new Error().stack, + "Use the `Deno.TlsCertifiedKeyPem.cert` option instead.", + ); + return op_tls_key_static(certChain, privateKey); } else if (cert !== undefined) { return op_tls_key_static(cert, key); } else { @@ -169,10 +228,6 @@ function loadTlsKeyPair( function listenTls({ port, - cert, - certFile, - key, - keyFile, hostname = "0.0.0.0", transport = "tcp", alpnProtocols = undefined, @@ -181,22 +236,11 @@ function listenTls({ if (transport !== "tcp") { throw new TypeError(`Unsupported transport: '${transport}'`); } - if (keyFile !== undefined) { - internals.warnOnDeprecatedApi( - "Deno.ListenTlsOptions.keyFile", - new Error().stack, - "Pass the key file contents to the `Deno.ListenTlsOptions.key` option instead.", - ); - } - if (certFile !== undefined) { - internals.warnOnDeprecatedApi( - "Deno.ListenTlsOptions.certFile", - new Error().stack, - "Pass the cert file contents to the `Deno.ListenTlsOptions.cert` option instead.", - ); - } - const keyPair = loadTlsKeyPair(cert, certFile, key, keyFile); + if (!hasTlsKeyPairOptions(arguments[0])) { + throw new TypeError("A key and certificate are required for `listenTls`"); + } + const keyPair = loadTlsKeyPair("Deno.listenTls", arguments[0]); const { 0: rid, 1: localAddr } = op_net_listen_tls( { hostname, port: Number(port) }, { alpnProtocols, reusePort }, diff --git a/ext/net/lib.deno_net.d.ts b/ext/net/lib.deno_net.d.ts index 597b3d3483..4b88b154aa 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; + /** 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; + /** @category Network */ export interface StartTlsOptions { /** A literal IP address or host name that can be resolved to an IP address. diff --git a/tests/unit/tls_test.ts b/tests/unit/tls_test.ts index 8f0a296c72..5be05b73e3 100644 --- a/tests/unit/tls_test.ts +++ b/tests/unit/tls_test.ts @@ -1336,7 +1336,7 @@ Deno.test( }); }, TypeError, - "Cannot specify both `privateKey` and `key`", + "Cannot specify both `key` and `privateKey` for `Deno.connectTls`.", ); }, );