Merge pull request #62 from mjcheetham/proxy

Use Git's HTTP proxy configuration

Author: mjcheetham

Git-Credential-Manager.sln

@@ -63,6 +63,7 @@ ProjectSection(SolutionItems) = preProject
 	docs\faq.md = docs\faq.md
 	docs\migration.md = docs\migration.md
 	docs\usage.md = docs\usage.md
+	docs\netconfig.md = docs\netconfig.md
 EndProjectSection
 EndProject
 Global

docs/configuration.md

@@ -92,3 +92,21 @@ git config --global credential.tfsonprem123.allowWindowsAuth false
 ```
 
 **Also see: [GCM_ALLOW_WINDOWSAUTH](environment.md#GCM_ALLOW_WINDOWSAUTH)**
+
+---
+
+### credential.httpProxy _(deprecated)_
+
+> This setting is deprecated and should be replaced by the [standard `http.proxy` Git configuration option](https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpproxy).
+>
+> Click [here](https://aka.ms/gcmcore-httpproxy) for more information.
+
+Configure GCM Core to use the a proxy for network operations.
+
+**Note:** Git itself does _not_ respect this setting; this affects GCM _only_.
+
+```shell
+git config --global credential.httpsProxy http://john.doe:[email protected]
+```
+
+**Also see: [GCM_HTTP_PROXY](environment.md#GCM_HTTP_PROXY-deprecated)**

docs/environment.md

@@ -120,6 +120,7 @@ Defaults to disabled.
 _No configuration equivalent._
 
 ---
+
 ### GCM_PROVIDER
 
 Define the host provider to use when authenticating.
@@ -214,3 +215,29 @@ export GCM_ALLOW_WINDOWSAUTH=0
 ```
 
 **Also see: [credential.allowWindowsAuth](environment.md#credentialallowWindowsAuth)**
+
+---
+
+### GCM_HTTP_PROXY _(deprecated)_
+
+> This setting is deprecated and should be replaced by the [standard `http.proxy` Git configuration option](https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpproxy).
+>
+> Click [here](https://aka.ms/gcmcore-httpproxy) for more information.
+
+Configure GCM Core to use the a proxy for network operations.
+
+**Note:** Git itself does _not_ respect this setting; this affects GCM _only_.
+
+##### Windows
+
+```batch
+SET GCM_HTTP_PROXY=http://john.doe:[email protected]
+```
+
+##### macOS/Linux
+
+```bash
+export GCM_HTTP_PROXY=http://john.doe:[email protected]
+```
+
+**Also see: [credential.httpProxy](configuration.md#credentialhttpProxy-deprecated)**

docs/netconfig.md

@@ -0,0 +1,105 @@
+# Network and HTTP configuration
+
+Git Credential Manager Core's network and HTTP(S) behavior can be configured in a few different ways via [environment variables](environment.md) and [configuration options](configuration.md).
+
+## HTTP Proxy
+
+If your computer sits behind a network firewall that requires the use of a proxy server to reach repository remotes or the wider Internet, there are various methods for configuring GCM to use a proxy.
+
+The simplist way to configure a proxy for _all_ HTTP(S) remotes is to [use the standard Git HTTP(S) proxy setting `http.proxy`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpproxy).
+
+For example to configure a proxy for all remotes for the current user:
+
+```shell
+git config --global http.proxy http://proxy.example.com
+```
+
+To specify a proxy for a particular remote you can [use the `remote.<name>.proxy` repository-level setting](https://git-scm.com/docs/git-config#Documentation/git-config.txt-remoteltnamegtproxy), for example:
+
+```shell
+git config --local remote.origin.proxy http://proxy.example.com
+```
+
+The advantage to using these standard configuration options is that in addition to GCM being configured to use the proxy, Git itself will be configured at the same time. This is probably the most commonly desired case in environments behind an Internet-blocking firewall.
+
+### Authenticated proxies
+
+Some proxy servers do not accept anonymous connections and require authentication. In order to specify the credentials to be used with a proxy, you can specify the username and password as part of the proxy URL setting.
+
+The format follows [RFC 3986 section 3.2.1](https://tools.ietf.org/html/rfc3986#section-3.2.1) by including the credentials in the 'user information' part of the URI. The password is optional.
+
+```text
+protocol://username[:password]@hostname
+```
+
+For example, to specify the username `john.doe` and the password `letmein123` for the proxy server `proxy.example.com`:
+
+```text
+https://john.doe:[email protected]
+```
+
+If you have special characters (as defined by [RFC 3986 section 2.2](https://tools.ietf.org/html/rfc3986#section-2.2)) in your username or password such as `:`, `@`, or any other non-URL friendly character you can URL-encode them ([section 2.1](https://tools.ietf.org/html/rfc3986#section-2.2)).
+
+For example, a space character would be encoded with `%20`.
+
+### Other proxy options
+
+GCM Core supports other ways of configuring a proxy for convenience and compatibility.
+
+1. GCM-specific configuration options (_**only** respected by GCM; **deprecated**_):
+   - `credential.httpProxy`
+   - `credential.httpsProxy`
+1. cURL environment variables (_also respected by Git_):
+   - `HTTP_PROXY`
+   - `HTTPS_PROXY`
+   - `ALL_PROXY`
+1. `GCM_HTTP_PROXY` environment variable (_**only** respected by GCM; **deprecated**_)
+
+## TLS Verification
+
+If you are using self-signed TLS (SSL) certificates with a self-hosted host provider such as GitHub Enteprise Server or Azure DevOps Server (previously TFS), you may see the following error message when attempting to connect using Git and/or GCM:
+
+```shell
+$ git clone https://ghe.example.com/john.doe/myrepo
+fatal: The remote certificate is invalid according to the validation procedure.
+```
+
+The **recommended and safest option** is to acquire a TLS certificate signed by a public trusted certificate authority (CA). There are multiple public CAs; here is a non-exhaustive list to consider: [Let's Encrypt](https://letsencrypt.org/), [Comodo](https://www.comodoca.com/), [Digicert](https://www.digicert.com/), [GoDaddy](https://www.godaddy.com/web-security/ssl-certificate), [GlobalSign](https://www.globalsign.com/en/ssl/).
+
+If it is not possible to **obtain a TLS certifiate from a trusted 3rd party** then you should try to add the _specific_ self-signed certificate or one of the CA certificates in the verification chain to your operating system's trusted certificate store ([macOS](https://support.apple.com/en-gb/guide/keychain-access/kyca2431/mac), [Windows](https://blogs.technet.microsoft.com/sbs/2008/05/08/installing-a-self-signed-certificate-as-a-trusted-root-ca-in-windows-vista/)).
+
+If you are _unable_ to either **obtain a trusted certificate**, or trust the self-signed certificate you can disable certificate verification in Git and GCM.
+
+---
+**Security Warning** :warning:
+
+Disabling verification of TLS (SSL) certificates removes protection against a [man-in-the-middle (MITM) attack](https://en.wikipedia.org/wiki/Man-in-the-middle_attack).
+
+Only disable certificate verification if you are sure you need to, are aware of all of the risks, and are unable to trust specific self-signed certificates (as described above).
+
+---
+
+The [environment variable `GIT_SSL_NO_VERIFY`](https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#_networking) and [Git configuration option `http.sslVerify`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpsslVerify) can be used to control TLS (SSL) certifcate verification.
+
+To disable verification for a specific remote (for example <https://example.com>):
+
+```shell
+git config --global http.https://example.com.sslVerify false
+```
+
+To disable verification for the current user for **_all remotes_** (**not recommended**):
+
+```shell
+# Environment variable (Windows)
+SET GIT_SSL_NO_VERIFY=1
+
+# Environment variable (macOS/Linux)
+export GIT_SSL_NO_VERIFY=1
+
+# Git configuration (Windows/macOS/Linux)
+git config --global http.sslVerify false
+```
+
+---
+
+**Note:** You may also experience similar verification errors if you are using a network traffic inspection tool such as [Telerik Fiddler](https://www.telerik.com/fiddler). If you are using such tools please consult their documentation for trusting the proxy root certificates.

src/shared/GitHub/GitHubAuthentication.cs

@@ -107,7 +107,7 @@ private bool TryFindHelperExecutablePath(out string path)
                 // We currently only have a helper on Windows. If we failed to find the helper we should warn the user.
                 if (PlatformUtils.IsWindows())
                 {
-                    Context.StdError.WriteLine($"warning: missing '{helperName}' from installation.");
+                    Context.Streams.Error.WriteLine($"warning: missing '{helperName}' from installation.");
                 }
 
                 return false;

src/shared/Microsoft.Git.CredentialManager.Tests/Commands/EraseCommandTests.cs

@@ -45,7 +45,10 @@ public async Task EraseCommand_ExecuteAsync_CallsHostProvider()
             providerMock.Setup(x => x.EraseCredentialAsync(It.IsAny<InputArguments>()))
                         .Returns(Task.CompletedTask);
             var providerRegistry = new TestHostProviderRegistry {Provider = providerMock.Object};
-            var context = new TestCommandContext {StdIn = stdin};
+            var context = new TestCommandContext
+            {
+                Streams = {In = stdin}
+            };
 
             string[] cmdArgs = {"erase"};
             var command = new EraseCommand(providerRegistry);

src/shared/Microsoft.Git.CredentialManager.Tests/Commands/GetCommandTests.cs

@@ -61,7 +61,7 @@ public async Task GetCommand_ExecuteAsync_CallsHostProviderAndWritesCredential()
 
             await command.ExecuteAsync(context, cmdArgs);
 
-            IDictionary<string, string> actualStdOutDict = ParseDictionary(context.StdOut);
+            IDictionary<string, string> actualStdOutDict = ParseDictionary(context.Streams.Out);
 
             providerMock.Verify(x => x.GetCredentialAsync(It.IsAny<InputArguments>()), Times.Once);
             Assert.Equal(expectedStdOutDict, actualStdOutDict);

src/shared/Microsoft.Git.CredentialManager.Tests/Commands/HostProviderCommandBaseTests.cs

@@ -15,6 +15,7 @@ public class HostProviderCommandBaseTests
         public async Task HostProviderCommandBase_ExecuteAsync_CallsExecuteInternalAsyncWithCorrectArgs()
         {
             var mockContext = new Mock<ICommandContext>();
+            var mockStreams = new Mock<IStandardStreams>();
             var mockProvider = new Mock<IHostProvider>();
             var mockHostRegistry = new Mock<IHostProviderRegistry>();
 
@@ -28,7 +29,8 @@ public async Task HostProviderCommandBase_ExecuteAsync_CallsExecuteInternalAsync
             string standardIn = "protocol=test\nhost=example.com\npath=a/b/c\n\n";
             TextReader standardInReader = new StringReader(standardIn);
 
-            mockContext.Setup(x => x.StdIn).Returns(standardInReader);
+            mockStreams.Setup(x => x.In).Returns(standardInReader);
+            mockContext.Setup(x => x.Streams).Returns(mockStreams.Object);
             mockContext.Setup(x => x.Trace).Returns(Mock.Of<ITrace>());
             mockContext.Setup(x => x.Settings).Returns(Mock.Of<ISettings>());
 
@@ -51,6 +53,7 @@ public async Task HostProviderCommandBase_ExecuteAsync_CallsExecuteInternalAsync
         public async Task HostProviderCommandBase_ExecuteAsync_ConfiguresSettingsRemoteUri()
         {
             var mockContext = new Mock<ICommandContext>();
+            var mockStreams = new Mock<IStandardStreams>();
             var mockProvider = new Mock<IHostProvider>();
             var mockSettings = new Mock<ISettings>();
             var mockHostRegistry = new Mock<IHostProviderRegistry>();
@@ -65,7 +68,8 @@ public async Task HostProviderCommandBase_ExecuteAsync_ConfiguresSettingsRemoteU
 
             mockSettings.SetupProperty(x => x.RemoteUri);
 
-            mockContext.Setup(x => x.StdIn).Returns(standardInReader);
+            mockStreams.Setup(x => x.In).Returns(standardInReader);
+            mockContext.Setup(x => x.Streams).Returns(mockStreams.Object);
             mockContext.Setup(x => x.Trace).Returns(Mock.Of<ITrace>());
             mockContext.Setup(x => x.Settings).Returns(mockSettings.Object);
 

src/shared/Microsoft.Git.CredentialManager.Tests/Commands/StoreCommandTests.cs

@@ -52,7 +52,10 @@ public async Task StoreCommand_ExecuteAsync_CallsHostProvider()
             providerMock.Setup(x => x.StoreCredentialAsync(It.IsAny<InputArguments>()))
                         .Returns(Task.CompletedTask);
             var providerRegistry = new TestHostProviderRegistry {Provider = providerMock.Object};
-            var context = new TestCommandContext {StdIn = stdin};
+            var context = new TestCommandContext
+            {
+                Streams = {In = stdin}
+            };
 
             string[] cmdArgs = {"store"};
             var command = new StoreCommand(providerRegistry);

src/shared/Microsoft.Git.CredentialManager.Tests/HttpClientFactoryTests.cs

@@ -1,6 +1,10 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
+using System;
+using System.Net;
 using System.Net.Http;
+using Moq;
+using Microsoft.Git.CredentialManager.Tests.Objects;
 using Xunit;
 
 namespace Microsoft.Git.CredentialManager.Tests
@@ -10,7 +14,7 @@ public class HttpClientFactoryTests
         [Fact]
         public void HttpClientFactory_GetClient_SetsDefaultHeaders()
         {
-            var factory = new HttpClientFactory();
+            var factory = new HttpClientFactory(Mock.Of<ITrace>(), Mock.Of<ISettings>(), new TestStandardStreams());
 
             HttpClient client = factory.CreateClient();
 
@@ -22,12 +26,105 @@ public void HttpClientFactory_GetClient_SetsDefaultHeaders()
         [Fact]
         public void HttpClientFactory_GetClient_MultipleCalls_ReturnsNewInstance()
         {
-            var factory = new HttpClientFactory();
+            var factory = new HttpClientFactory(Mock.Of<ITrace>(), Mock.Of<ISettings>(), new TestStandardStreams());
 
             HttpClient client1 = factory.CreateClient();
             HttpClient client2 = factory.CreateClient();
 
             Assert.NotSame(client1, client2);
         }
+
+        [Fact]
+        public void HttpClientFactory_TryCreateProxy_NoProxy_ReturnsFalseOutNull()
+        {
+            const string repoPath = "/tmp/repos/foo";
+            const string repoRemote  = "https://remote.example.com/foo.git";
+            var repoRemoteUri = new Uri(repoRemote);
+
+            var settings = new TestSettings
+            {
+                RemoteUri = repoRemoteUri,
+                RepositoryPath = repoPath
+            };
+            var httpFactory = new HttpClientFactory(Mock.Of<ITrace>(), settings, Mock.Of<IStandardStreams>());
+
+            bool result = httpFactory.TryCreateProxy(out IWebProxy proxy);
+
+            Assert.False(result);
+            Assert.Null(proxy);
+        }
+
+        [Fact]
+        public void HttpClientFactory_TryCreateProxy_ProxyNoCredentials_ReturnsTrueOutProxyWithUrlDefaultCredentials()
+        {
+            const string repoPath = "/tmp/repos/foo";
+            const string repoRemote = "https://remote.example.com/foo.git";
+            var repoRemoteUri = new Uri(repoRemote);
+
+            string proxyConfigString = "https://proxy.example.com/git";
+            string expectedProxyUrl = proxyConfigString;
+
+            var settings = new TestSettings
+            {
+                RemoteUri = repoRemoteUri,
+                RepositoryPath = repoPath,
+                ProxyConfiguration = new Uri(proxyConfigString)
+            };
+            var httpFactory = new HttpClientFactory(Mock.Of<ITrace>(), settings, Mock.Of<IStandardStreams>());
+
+            bool result = httpFactory.TryCreateProxy(out IWebProxy proxy);
+
+            Assert.True(result);
+            Assert.NotNull(proxy);
+            var configuredProxyUrl = proxy.GetProxy(repoRemoteUri);
+            Assert.Equal(expectedProxyUrl, configuredProxyUrl.ToString());
+
+            AssertDefaultCredentials(proxy.Credentials);
+        }
+
+        [Fact]
+        public void HttpClientFactory_TryCreateProxy_ProxyWithCredentials_ReturnsTrueOutProxyWithUrlConfiguredCredentials()
+        {
+            const string proxyScheme = "https";
+            const string proxyUser   = "john.doe";
+            const string proxyPass   = "letmein";
+            const string proxyHost   = "proxy.example.com/git";
+            const string repoPath    = "/tmp/repos/foo";
+            const string repoRemote  = "https://remote.example.com/foo.git";
+
+            string proxyConfigString = $"{proxyScheme}://{proxyUser}:{proxyPass}@{proxyHost}";
+            string expectedProxyUrl  = $"{proxyScheme}://{proxyHost}";
+            var repoRemoteUri = new Uri(repoRemote);
+
+            var settings = new TestSettings
+            {
+                RemoteUri = repoRemoteUri,
+                RepositoryPath = repoPath,
+                ProxyConfiguration = new Uri(proxyConfigString)
+            };
+            var httpFactory = new HttpClientFactory(Mock.Of<ITrace>(), settings, Mock.Of<IStandardStreams>());
+
+            bool result = httpFactory.TryCreateProxy(out IWebProxy proxy);
+
+            Assert.True(result);
+            Assert.NotNull(proxy);
+            var configuredProxyUrl = proxy.GetProxy(repoRemoteUri);
+            Assert.Equal(expectedProxyUrl, configuredProxyUrl.ToString());
+
+            Assert.NotNull(proxy.Credentials);
+            Assert.IsType<NetworkCredential>(proxy.Credentials);
+            var configuredCredentials = (NetworkCredential) proxy.Credentials;
+            Assert.Equal(proxyUser, configuredCredentials.UserName);
+            Assert.Equal(proxyPass, configuredCredentials.Password);
+        }
+
+        private static void AssertDefaultCredentials(ICredentials credentials)
+        {
+            var netCred = (NetworkCredential) credentials;
+
+            Assert.Equal(string.Empty, netCred.Domain);
+            Assert.Equal(string.Empty, netCred.UserName);
+            Assert.Equal(string.Empty, netCred.Password);
+        }
     }
 }