diff options
Diffstat (limited to 'ext/net')
| -rw-r--r-- | ext/net/02_tls.js | 176 | ||||
| -rw-r--r-- | ext/net/lib.deno_net.d.ts | 139 |
2 files changed, 217 insertions, 98 deletions
diff --git a/ext/net/02_tls.js b/ext/net/02_tls.js index 8d43e8604..003c5336a 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, + alpnProtocols = undefined, + keyFormat = undefined, cert = undefined, + certFile = undefined, + certChain = undefined, key = undefined, - alpnProtocols = 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`", - ); - } - if (privateKey !== undefined && key !== undefined) { - throw new TypeError( - "Cannot specify both `privateKey` and `key`", + 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; } - 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", - ); + 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}\`.`, + ); + } } - if ((cert !== undefined) ^ (key !== undefined)) { - throw new TypeError("If cert is specified, key must also be specified"); + + // 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 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. |