development/deno
development/deno
1
0
Fork 0
mirror of https://github.com/denoland/deno synced 2024-10-02 14:23:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(ext/net): extract TLS key and certificate from interfaces (#23296)

Browse source 
Removes the certificate options from all the interfaces and replaces
them with a new `TlsCertifiedKeyOptions`. This allows us to centralize
the documentation for TLS key management for both client and server, and
will allow us to add key object support in the future.

Also adds an option `keyFormat` field to the cert/key that must be
omitted or set to `pem`. This will allow us to load other format keys in
the future `der`, `pfx`, etc.

In a future PR, we will add a way to load a certified key object, and we
will add another option to `TlsCertifiedKeyOptions` like so:

```ts
export interface TlsCertifiedKeyOptions =
    | TlsCertifiedKeyPem
    | TlsCertifiedKeyFromFile
    | TlsCertifiedKeyConnectTls
    | { key: Deno.CertifiedKey }
```
This commit is contained in:
Matt Mastracci 2024-04-09 16:23:22 -06:00 committed by GitHub
parent f23155bca7
commit e190acbfa8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 243 additions and 118 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
cli/tsc/dts/lib.deno.ns.d.ts vendored
View file

@ -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

25
cli/tsc/dts/lib.deno.unstable.d.ts vendored
View file

@ -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.

7
ext/fetch/22_http_client.js
View file

@ -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,

180
ext/net/02_tls.js
View file

@ -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 },

139
ext/net/lib.deno_net.d.ts vendored
View file

@ -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.

2
tests/unit/tls_test.ts
View file

@ -1336,7 +1336,7 @@ Deno.test(
});
},
TypeError,
"Cannot specify both `privateKey` and `key`",
"Cannot specify both `key` and `privateKey` for `Deno.connectTls`.",
);
},
);