From d620ade9b7868b711a63f8d609ee00e51b89a561 Mon Sep 17 00:00:00 2001 From: Flor Elisa Chacon Ochoa Date: Wed, 7 Feb 2024 14:29:09 -0800 Subject: [PATCH 1/8] Add spec for proxy support --- doc/specs/#190 - Proxy Support.md | 86 +++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 doc/specs/#190 - Proxy Support.md diff --git a/doc/specs/#190 - Proxy Support.md b/doc/specs/#190 - Proxy Support.md new file mode 100644 index 0000000000..89923547ce --- /dev/null +++ b/doc/specs/#190 - Proxy Support.md @@ -0,0 +1,86 @@ +--- +author: Flor Chacon @florelis +created on: 2024-02-07 +last updated: 2024-02-07 +issue id: 190 +--- + +# Proxy support + +For [#190](https://github.com/microsoft/winget-cli/issues/190) + +## Abstract + +This spec describes a feature to specify a proxy for winget to use when connecting to the internet. + +## Solution Design + +A new command line argument will be added to specify a proxy to use during a particular invocation of winget. + +An option to set a default proxy to use on every flow will be added, but it will be gated to require aministrator permissions. + +New Group Policy will also be added for IT admins to control the use of proxies. +The policies will be similar to those we already have for sources, so that a specific proxy can be required or only a predefined set of proxies can be allowed. + +Proxies will not be used for the configuration features for now. + +If a proxy is configured, it will be used for accessing sources and downloading installers. +Note that it will not affect the behavior of installers themselves, so an installation may still generate traffic outside of the proxy. + +## UI/UX Design + +We will add a command line argument taking the URI to the proxy. +A separate parameter will be available to disable the use of proxy if there is a default set. + +``` +> winget install Contoso.App --proxy https://127.0.0.1:2345 +> winget install Contoso.App --no-proxy +``` + +To configure the default proxy, a new `proxy` subcommand will be added to the `settings` command, with options to `set` and `reset` the default. + +``` +> winget settings proxy set https://127.0.0.1:2345 +> winget settings proxy reset +``` + +The current default proxy will be added to the output `winget --info`. + +## Capabilities + +### Accessibility + +This should have no direct impact on accessibility. + +### Security + +There is a possibility of an attacker using a malicious proxy to tamper with the data received from the source, or with the contents of the installer file. +This is not much different from the risks of using a public network. +The following mitigating factors will be in place: +* (New) The ability to set a default proxy will be restricted to administrators, to prevent attackers from adding a proxy without the user realizing. +* (New) A Group Policy will be available to block the use of proxies, or limit it to an approved list. +* Pre-indexed sources need to be signed, and the publisher is required to match during source update. + When initially adding the source, administrator privileges are already required to limit misuse. +* Pre-indexed sources include manifest hashes in the local database, to ensure that the manifest downloaded later is as expected. +* For the Microsoft Store source, we use certificate pinning to ensure we are talking to the right server. +* Manifests include a hash of the installer that is validated before executing it. + The ability to ignore installer hash mismatches requires administrator privileges. + +### Compatibility + +No breaking changes to existing behavior. + +### Performance, Power, and Efficiency + +There should not be any notable performance changes. + +## Potential Issues + +A faulty or misconfigured proxy could impact most of winget's functionality, but it can be worked around by disabling the use of the proxy. + +## Future considerations + +Things we may want to consider in the future: +* Extend support for proxies to the Configuration feature +* Add proxy support to the COM API +* Add support for proxies that require authentiation From 9576adcf95f6942a96b9da57fa84e4f69d05414f Mon Sep 17 00:00:00 2001 From: Flor Elisa Chacon Ochoa Date: Wed, 7 Feb 2024 14:38:48 -0800 Subject: [PATCH 2/8] Fix speling --- .github/actions/spelling/allow.txt | 1 + doc/specs/#190 - Proxy Support.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/actions/spelling/allow.txt b/.github/actions/spelling/allow.txt index f4e5922a5e..37c9a3f68b 100644 --- a/.github/actions/spelling/allow.txt +++ b/.github/actions/spelling/allow.txt @@ -105,6 +105,7 @@ FILEOS FILESINUSE FILESUBTYPE FILEVERSION +florelis FLUSHEACHLINE forcerestart gdi diff --git a/doc/specs/#190 - Proxy Support.md b/doc/specs/#190 - Proxy Support.md index 89923547ce..9c641bd9d4 100644 --- a/doc/specs/#190 - Proxy Support.md +++ b/doc/specs/#190 - Proxy Support.md @@ -17,7 +17,7 @@ This spec describes a feature to specify a proxy for winget to use when connecti A new command line argument will be added to specify a proxy to use during a particular invocation of winget. -An option to set a default proxy to use on every flow will be added, but it will be gated to require aministrator permissions. +An option to set a default proxy to use on every flow will be added, but it will be gated to require administrator permissions. New Group Policy will also be added for IT admins to control the use of proxies. The policies will be similar to those we already have for sources, so that a specific proxy can be required or only a predefined set of proxies can be allowed. @@ -83,4 +83,4 @@ A faulty or misconfigured proxy could impact most of winget's functionality, but Things we may want to consider in the future: * Extend support for proxies to the Configuration feature * Add proxy support to the COM API -* Add support for proxies that require authentiation +* Add support for proxies that require authentication From 9c096c88a933f27c9182bc7ca9709bee110c2b79 Mon Sep 17 00:00:00 2001 From: Flor Elisa Chacon Ochoa Date: Thu, 8 Feb 2024 10:56:12 -0800 Subject: [PATCH 3/8] PR comments --- doc/specs/#190 - Proxy Support.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/specs/#190 - Proxy Support.md b/doc/specs/#190 - Proxy Support.md index 9c641bd9d4..55804509cc 100644 --- a/doc/specs/#190 - Proxy Support.md +++ b/doc/specs/#190 - Proxy Support.md @@ -16,8 +16,9 @@ This spec describes a feature to specify a proxy for winget to use when connecti ## Solution Design A new command line argument will be added to specify a proxy to use during a particular invocation of winget. +This functionality will first need to be enabled through an admin setting, slimilar to local manifests or hash override. -An option to set a default proxy to use on every flow will be added, but it will be gated to require administrator permissions. +An option to set a default proxy to use on every flow will be added, but it will require administrator permissions to be set. New Group Policy will also be added for IT admins to control the use of proxies. The policies will be similar to those we already have for sources, so that a specific proxy can be required or only a predefined set of proxies can be allowed. @@ -33,6 +34,7 @@ We will add a command line argument taking the URI to the proxy. A separate parameter will be available to disable the use of proxy if there is a default set. ``` +> winget settings --enable ProxyCommandLineArgument > winget install Contoso.App --proxy https://127.0.0.1:2345 > winget install Contoso.App --no-proxy ``` @@ -63,6 +65,7 @@ The following mitigating factors will be in place: When initially adding the source, administrator privileges are already required to limit misuse. * Pre-indexed sources include manifest hashes in the local database, to ensure that the manifest downloaded later is as expected. * For the Microsoft Store source, we use certificate pinning to ensure we are talking to the right server. +* When communicating with REST sources, the certificate used by the source for HTTPS needs to match the domain. * Manifests include a hash of the installer that is validated before executing it. The ability to ignore installer hash mismatches requires administrator privileges. From d9aef9ff2a2f14f857eca97a4727db6df2b5e7a9 Mon Sep 17 00:00:00 2001 From: Flor Elisa Chacon Ochoa Date: Thu, 8 Feb 2024 11:02:01 -0800 Subject: [PATCH 4/8] Spelling --- doc/specs/#190 - Proxy Support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/specs/#190 - Proxy Support.md b/doc/specs/#190 - Proxy Support.md index 55804509cc..e48cf845d8 100644 --- a/doc/specs/#190 - Proxy Support.md +++ b/doc/specs/#190 - Proxy Support.md @@ -16,7 +16,7 @@ This spec describes a feature to specify a proxy for winget to use when connecti ## Solution Design A new command line argument will be added to specify a proxy to use during a particular invocation of winget. -This functionality will first need to be enabled through an admin setting, slimilar to local manifests or hash override. +This functionality will first need to be enabled through an admin setting, similar to local manifests or hash override. An option to set a default proxy to use on every flow will be added, but it will require administrator permissions to be set. From 88884822c5884eb1d818a498dac27956d88daea8 Mon Sep 17 00:00:00 2001 From: Flor Elisa Chacon Ochoa Date: Tue, 13 Feb 2024 13:54:32 -0800 Subject: [PATCH 5/8] PR comments --- doc/specs/#190 - Proxy Support.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/doc/specs/#190 - Proxy Support.md b/doc/specs/#190 - Proxy Support.md index e48cf845d8..6a80f85b97 100644 --- a/doc/specs/#190 - Proxy Support.md +++ b/doc/specs/#190 - Proxy Support.md @@ -31,7 +31,8 @@ Note that it will not affect the behavior of installers themselves, so an instal ## UI/UX Design We will add a command line argument taking the URI to the proxy. -A separate parameter will be available to disable the use of proxy if there is a default set. +A separate argument will be available to disable the use of proxy if there is a default set. +Both of these arguments will be disabled by default and require admin privileges to enable. ``` > winget settings --enable ProxyCommandLineArgument @@ -40,6 +41,7 @@ A separate parameter will be available to disable the use of proxy if there is a ``` To configure the default proxy, a new `proxy` subcommand will be added to the `settings` command, with options to `set` and `reset` the default. +This will require admin privileges and does not require `ProxyCommandLineArgument` to be enabled. ``` > winget settings proxy set https://127.0.0.1:2345 @@ -60,14 +62,14 @@ There is a possibility of an attacker using a malicious proxy to tamper with the This is not much different from the risks of using a public network. The following mitigating factors will be in place: * (New) The ability to set a default proxy will be restricted to administrators, to prevent attackers from adding a proxy without the user realizing. -* (New) A Group Policy will be available to block the use of proxies, or limit it to an approved list. +* (New) A Group Policy will be available to block the use of proxies, require the use of a specific proxy, or limit them to an approved list. * Pre-indexed sources need to be signed, and the publisher is required to match during source update. When initially adding the source, administrator privileges are already required to limit misuse. * Pre-indexed sources include manifest hashes in the local database, to ensure that the manifest downloaded later is as expected. * For the Microsoft Store source, we use certificate pinning to ensure we are talking to the right server. * When communicating with REST sources, the certificate used by the source for HTTPS needs to match the domain. * Manifests include a hash of the installer that is validated before executing it. - The ability to ignore installer hash mismatches requires administrator privileges. + The ability to ignore installer hash mismatches is disabled by default, and enabling it requires administrator privileges. ### Compatibility @@ -87,3 +89,5 @@ Things we may want to consider in the future: * Extend support for proxies to the Configuration feature * Add proxy support to the COM API * Add support for proxies that require authentication +* Add the ability for admins to set multiple allowed proxies that a user can use +* Add the ability to specify a different default proxy for each source From 2c20ecd793a9093e274330559244d0bebdffc4c5 Mon Sep 17 00:00:00 2001 From: Flor Elisa Chacon Ochoa Date: Mon, 26 Feb 2024 10:46:33 -0800 Subject: [PATCH 6/8] Update spec --- doc/specs/#190 - Proxy Support.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/doc/specs/#190 - Proxy Support.md b/doc/specs/#190 - Proxy Support.md index 6a80f85b97..ed8029e40c 100644 --- a/doc/specs/#190 - Proxy Support.md +++ b/doc/specs/#190 - Proxy Support.md @@ -24,9 +24,13 @@ New Group Policy will also be added for IT admins to control the use of proxies. The policies will be similar to those we already have for sources, so that a specific proxy can be required or only a predefined set of proxies can be allowed. Proxies will not be used for the configuration features for now. +Proxy settings in winget will not affect the behavior of installers themselves, so an installation may still generate traffic outside of the proxy. -If a proxy is configured, it will be used for accessing sources and downloading installers. -Note that it will not affect the behavior of installers themselves, so an installation may still generate traffic outside of the proxy. +The proxy will be used to download the installers and access the sources. + +Since the APIs used for Delivery Optimization and MSIX deployment do not provide a way to specify a custom proxy, if a proxy is specified, we will change the use of those APIs to accomodate the proxy. +For Delivery Optimization, a proxy will force use of WinINet instead. +For MSIX deployment, the packages will be fully downloaded before deploying; this will require more network traffic than a streaming install of only the required bits. ## UI/UX Design @@ -91,3 +95,4 @@ Things we may want to consider in the future: * Add support for proxies that require authentication * Add the ability for admins to set multiple allowed proxies that a user can use * Add the ability to specify a different default proxy for each source +* Use proxies with Delivery Optimization. This requires changes to the Delivery Optimization APIs. From 7060c83fd398584e341c07115c16cc9e47e31517 Mon Sep 17 00:00:00 2001 From: Flor Elisa Chacon Ochoa Date: Fri, 15 Mar 2024 11:21:35 -0700 Subject: [PATCH 7/8] Update settings command syntax --- doc/specs/#190 - Proxy Support.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/specs/#190 - Proxy Support.md b/doc/specs/#190 - Proxy Support.md index ed8029e40c..c15b8ba25b 100644 --- a/doc/specs/#190 - Proxy Support.md +++ b/doc/specs/#190 - Proxy Support.md @@ -44,12 +44,12 @@ Both of these arguments will be disabled by default and require admin privileges > winget install Contoso.App --no-proxy ``` -To configure the default proxy, a new `proxy` subcommand will be added to the `settings` command, with options to `set` and `reset` the default. +To configure the default proxy, new `set` and `reset` subcommands will be added to the `settings` command, , with options to `set` and `reset` the default. This will require admin privileges and does not require `ProxyCommandLineArgument` to be enabled. ``` -> winget settings proxy set https://127.0.0.1:2345 -> winget settings proxy reset +> winget settings set DefaultProxy https://127.0.0.1:2345 +> winget settings reset DefaultProxy ``` The current default proxy will be added to the output `winget --info`. From 2f1654b5bf6f246ca9e61324c0f4bcdc60521b13 Mon Sep 17 00:00:00 2001 From: Flor Elisa Chacon Ochoa Date: Fri, 15 Mar 2024 11:24:15 -0700 Subject: [PATCH 8/8] Forgot to hit save... --- doc/specs/#190 - Proxy Support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/specs/#190 - Proxy Support.md b/doc/specs/#190 - Proxy Support.md index c15b8ba25b..bec6fbe992 100644 --- a/doc/specs/#190 - Proxy Support.md +++ b/doc/specs/#190 - Proxy Support.md @@ -44,7 +44,7 @@ Both of these arguments will be disabled by default and require admin privileges > winget install Contoso.App --no-proxy ``` -To configure the default proxy, new `set` and `reset` subcommands will be added to the `settings` command, , with options to `set` and `reset` the default. +To configure the default proxy, new `set` and `reset` subcommands will be added to the `settings` command. This will require admin privileges and does not require `ProxyCommandLineArgument` to be enabled. ```