Merge pull request #464 from mjcheetham/dpapi

Add DPAPI based credential store on Windows

Author: mjcheetham

Git-Credential-Manager.sln

@@ -33,32 +33,6 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Installer.Windows", "src\wi
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Payload.Windows", "src\windows\Payload.Windows\Payload.Windows.csproj", "{8DBBAB0A-970D-4BE3-958C-8CDC92F76549}"
 EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "assets", "assets", "{65E53644-7FB7-4EC2-8C41-4356F7A4C0C4}"
-	ProjectSection(SolutionItems) = preProject
-		assets\gcm-transparent.png = assets\gcm-transparent.png
-		assets\gcmicon.ico = assets\gcmicon.ico
-		assets\gcmicon128.bmp = assets\gcmicon128.bmp
-		assets\gcmicon16.bmp = assets\gcmicon16.bmp
-		assets\gcmicon256.bmp = assets\gcmicon256.bmp
-		assets\gcmicon32.bmp = assets\gcmicon32.bmp
-		assets\gcmicon64.bmp = assets\gcmicon64.bmp
-		assets\gcmweb.png = assets\gcmweb.png
-	EndProjectSection
-EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{83BD5957-AC75-4072-A3D1-ABF3A71951F5}"
-	ProjectSection(SolutionItems) = preProject
-		docs\configuration.md = docs\configuration.md
-		docs\development.md = docs\development.md
-		docs\environment.md = docs\environment.md
-		docs\faq.md = docs\faq.md
-		docs\migration.md = docs\migration.md
-		docs\netconfig.md = docs\netconfig.md
-		docs\usage.md = docs\usage.md
-		docs\architecture.md = docs\architecture.md
-		docs\hostprovider.md = docs\hostprovider.md
-		docs\linuxcredstores.md = docs\linuxcredstores.md
-	EndProjectSection
-EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GitHub.UI.Windows", "src\windows\GitHub.UI.Windows\GitHub.UI.Windows.csproj", "{4C2DBC8A-B3F2-4C64-870A-BA79DA4BD403}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Atlassian.Bitbucket", "src\shared\Atlassian.Bitbucket\Atlassian.Bitbucket.csproj", "{B49881A6-E734-490E-8EA7-FB0D9E296CFB}"

Git-Credential-Manager.sln.DotSettings

@@ -1,4 +1,5 @@
 <wpf:ResourceDictionary xml:space="preserve" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:s="clr-namespace:System;assembly=mscorlib" xmlns:ss="urn:shemas-jetbrains-com:settings-storage-xaml" xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
+	<s:String x:Key="/Default/CodeStyle/Naming/CSharpNaming/Abbreviations/=OS/@EntryIndexedValue">OS</s:String>
 	<s:String x:Key="/Default/Environment/Hierarchy/Build/SolBuilderDuo/UseMsbuildSolutionBuilder/@EntryValue">No</s:String>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=PKCE/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Bitbucket/@EntryIndexedValue">True</s:Boolean></wpf:ResourceDictionary>

README.md

@@ -21,7 +21,7 @@ Git Credential Manager Core is currently available for Windows, macOS, and Linux
 Feature|Windows|macOS|Linux
 -|:-:|:-:|:-:
 Installer/uninstaller|✓|✓|✓\*
-Secure platform credential storage|&#10003;<br/>Windows<br/>Credential<br/>Manager|&#10003;<br/>macOS Keychain|&#10003;<br/>1. Secret Service<br/>2. `pass`/GPG<br/>3. `credential-cache`<br/>4. Plaintext files<br/>[(see more)](docs/linuxcredstores.md)
+Secure platform credential storage|&#10003;<br/>[(see more)](docs/credstores.md)|&#10003;<br/>[(see more)](docs/credstores.md)|&#10003;<br/>[(see more)](docs/credstores.md)
 Multi-factor authentication support for Azure DevOps|&#10003;|&#10003;|&#10003;
 Two-factor authentication support for GitHub|&#10003;|&#10003;|&#10003;
 Two-factor authentication support for Bitbucket|&#10003;|&#10003;|&#10003;
@@ -128,7 +128,7 @@ tar -xvf <path-to-tarball> -C /usr/local/bin
 git-credential-manager-core configure
 ```
 
-**Note:** all Linux distributions [require additional configuration](https://aka.ms/gcmcore-linuxcredstores) to use GCM Core.
+**Note:** all Linux distributions [require additional configuration](https://aka.ms/gcmcore-credstores) to use GCM Core.
 
 ---
 
@@ -191,9 +191,12 @@ See detailed information [here](https://aka.ms/gcmcore-httpproxy).
 - [Environment variables](docs/environment.md)
 - [Enterprise configuration](docs/enterprise-config.md)
 - [Network and HTTP configuration](docs/netconfig.md)
+- [Credential stores](docs/credstores.md)
 - [Architectural overview](docs/architecture.md)
 - [Host provider specification](docs/hostprovider.md)
-- [Linux credential stores](docs/linuxcredstores.md)
+
+## Experimental Features
+
 - [Windows broker (experimental)](docs/windows-broker.md)
 - [Azure Repos OAuth tokens (experimental)](docs/azrepos-users-and-tokens.md)
 

docs/configuration.md

@@ -219,17 +219,20 @@ git config --global credential.namespace "my-namespace"
 
 Select the type of credential store to use on supported platforms.
 
-Default value is unset.
+Default value on Windows is `wincredman`, on macOS is `keychain`, and is unset on Linux.
 
-**Note:** This setting is only supported on Linux platforms. Setting this value on Windows and macOS has no effect. See more information about configuring secret stores on Linux [here](linuxcredstores.md).
+**Note:** See more information about configuring secret stores [here](credstores.md).
 
-Value|Credential Store
--|-
-_(unset)_|(error)
-`secretservice`|[freedesktop.org Secret Service API](https://specifications.freedesktop.org/secret-service/) via [libsecret](https://wiki.gnome.org/Projects/Libsecret) (requires a graphical interface to unlock secret collections).
-`gpg`|Use GPG to store encrypted files that are compatible with the [`pass` utility](https://www.passwordstore.org/) (requires GPG and `pass` to initialize the store).
-`cache`|Git's built-in [credential cache](https://git-scm.com/docs/git-credential-cache).
-`plaintext`|Store credentials in plaintext files (**UNSECURE**). Customize the plaintext store location with [`credential.plaintextStorePath`](#credentialplaintextstorepath).
+Value|Credential Store|Platforms
+-|-|-
+_(unset)_|Windows: `wincredman`<br/>macOS: `keychain`<br/>Linux: _(none)_|-
+`wincredman`|Windows Credential Manager (not available over SSH).|Windows
+`dpapi`|DPAPI protected files. Customize the DPAPI store location with [credential.dpapiStorePath](#credentialdpapistorepath)|Windows
+`keychain`|macOS Keychain.|macOS
+`secretservice`|[freedesktop.org Secret Service API](https://specifications.freedesktop.org/secret-service/) via [libsecret](https://wiki.gnome.org/Projects/Libsecret) (requires a graphical interface to unlock secret collections).|Linux
+`gpg`|Use GPG to store encrypted files that are compatible with the [`pass` utility](https://www.passwordstore.org/) (requires GPG and `pass` to initialize the store).|macOS, Linux
+`cache`|Git's built-in [credential cache](https://git-scm.com/docs/git-credential-cache).|Windows, macOS, Linux
+`plaintext`|Store credentials in plaintext files (**UNSECURE**). Customize the plaintext store location with [`credential.plaintextStorePath`](#credentialplaintextstorepath).|Windows, macOS, Linux
 
 ##### Example
 
@@ -267,7 +270,7 @@ git config --global credential.cacheOptions "--timeout 300"
 
 Specify a custom directory to store plaintext credential files in when [`credential.credentialStore`](#credentialcredentialstore) is set to `plaintext`.
 
-Defaults to the value `~/.gcm/store`.
+Defaults to the value `~/.gcm/store` or `%USERPROFILE%\.gcm\store`.
 
 #### Example
 
@@ -279,6 +282,22 @@ git config --global credential.plaintextStorePath /mnt/external-drive/credential
 
 ---
 
+### credential.dpapiStorePath
+
+Specify a custom directory to store DPAPI protected credential files in when [`credential.credentialStore`](#credentialcredentialstore) is set to `dpapi`.
+
+Defaults to the value `%USERPROFILE%\.gcm\dpapi_store`.
+
+#### Example
+
+```batch
+git config --global credential.dpapiStorePath D:\credentials
+```
+
+**Also see: [GCM_DPAPI_STORE_PATH](environment.md#GCM_DPAPI_STORE_PATH)**
+
+---
+
 ### credential.msauthFlow
 
 Specify which authentication flow should be used when performing Microsoft authentication and an interactive flow is required.

docs/linuxcredstores.md renamed to docs/credstores.md

@@ -1,48 +1,131 @@
-# Credential stores on Linux
+# Credential stores
 
-There are four options for storing credentials that Git Credential
-Manager Core (GCM Core) manages on Linux platforms:
+There are several options for storing credentials that GCM Core supports:
 
-1. [freedesktop.org Secret Service API](https://specifications.freedesktop.org/secret-service/)
-2. GPG/[`pass`](https://www.passwordstore.org/) compatible files
-3. Git's built-in [credential cache](https://git-scm.com/docs/git-credential-cache)
-4. Plaintext files
+- Windows Credential Manager
+- macOS Keychain
+- [freedesktop.org Secret Service API](https://specifications.freedesktop.org/secret-service/)
+- GPG/[`pass`](https://www.passwordstore.org/) compatible files
+- Git's built-in [credential cache](https://git-scm.com/docs/git-credential-cache)
+- Plaintext files
 
-By default, GCM Core comes unconfigured. After running `git-credential-manager-core configure`, you can select which credential store
-to use by setting the [`GCM_CREDENTIAL_STORE`](environment.md#GCM_CREDENTIAL_STORE)
+The default credential stores on macOS and Windows are the macOS Keychain and
+the Windows Credential Manager, respectively.
+
+GCM comes without a default store on Linux distributions.
+
+You can select which credential store to use by setting the [`GCM_CREDENTIAL_STORE`](environment.md#GCM_CREDENTIAL_STORE)
 environment variable, or the [`credential.credentialStore`](configuration.md#credentialcredentialstore)
 Git configuration setting.
 
 Some credential stores have limitations, or further configuration required
-depending on your particular setup.
+depending on your particular setup. See more detailed information below for each
+credential store.
+
+## Windows Credential Manager
+
+**Available on:** _Windows_
+
+**This is the default store on Windows.**
+
+**:warning: Does not work over a network/SSH session.**
+
+```batch
+SET GCM_CREDENTIAL_STORE="wincredman"
+```
 
-## 1. [freedesktop.org Secret Service API](https://specifications.freedesktop.org/secret-service/)
+or
 
 ```shell
-export GCM_CREDENTIAL_STORE=secretservice
+git config --global credential.credentialStore wincredman
+```
+
+This credential store uses the Windows Credential APIs (`wincred.h`) to store
+data securely in the Windows Credential Manager (also known as the Windows
+Credential Vault in earlier versions of Windows).
+
+You can [access and manage data in the credential manager](https://support.microsoft.com/en-us/windows/accessing-credential-manager-1b5c916a-6a16-889f-8581-fc16e8165ac0)
+from the control panel, or via the [`cmdkey` command-line tool](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/cmdkey).
+
+When connecting to a Windows machine over a network session (such as SSH), GCM
+is unable to persist credentials to the Windows Credential Manager due to
+limitations in Windows. Connecting by Remote Desktop doesn't suffer from this
+limitation.
+
+## DPAPI protected files
+
+**Available on:** _Windows_
+
+```batch
+SET GCM_CREDENTIAL_STORE="dpapi"
+```
+
+or
+
+```shell
+git config --global credential.credentialStore dpapi
+```
+
+This credential store uses Windows DPAPI to encrypt credentials which are stored
+as files in your file system. The file structure is the same as the
+[plaintext files credential store](#plaintext-files) except the first line (the
+secret value) is protected by DPAPI.
+
+By default files are stored in `%USERPROFILE%\.gcm\dpapi_store`. This can be
+configured using the environment variable `GCM_DPAPI_STORE_PATH` environment
+variable.
+
+If the directory doesn't exist it will be created.
+
+## macOS Keychain
+
+**Available on:** _macOS_
+
+**This is the default store on macOS.**
+
+```shell
+export GCM_CREDENTIAL_STORE=keychain
 # or
-git config --global credential.credentialStore secretservice
+git config --global credential.credentialStore keychain
 ```
 
+This credential store uses the default macOS Keychain, which is typically the
+`login` keychain.
+
+You can [manage data stored in the keychain](https://support.apple.com/en-gb/guide/mac-help/mchlf375f392/mac)
+using the Keychain Access application.
+
+## [freedesktop.org Secret Service API](https://specifications.freedesktop.org/secret-service/)
+
+**Available on:** _Linux_
+
 **:warning: Requires a graphical user interface session.**
 
+```shell
+export GCM_CREDENTIAL_STORE=secretservice
+# or
+git config --global credential.credentialStore secretservice
+```
+
 This credential store uses the `libsecret` library to interact with the Secret
 Service. It stores credentials securely in 'collections', which can be viewed by
 tools such as `secret-tool` and `seahorse`.
 
 A graphical user interface is required in order to show a secure prompt to
 request a secret collection be unlocked.
 
-## 2. GPG/[`pass`](https://www.passwordstore.org/) compatible files
+## GPG/[`pass`](https://www.passwordstore.org/) compatible files
+
+**Available on:** _macOS, Linux_
+
+**:warning: Requires `gpg`, `pass`, and a GPG key pair.**
 
 ```shell
 export GCM_CREDENTIAL_STORE=gpg
 # or
 git config --global credential.credentialStore gpg
 ```
 
-**:warning: Requires `gpg`, `pass`, and a GPG key pair.**
-
 This credential store uses GPG to encrypt files containing credentials which are
 stored in your file system. The file structure is compatible with the popular
 [`pass`](https://www.passwordstore.org/) tool. By default files are stored in
@@ -88,7 +171,9 @@ export GPG_TTY=$(tty)
 **Note:** Using `/dev/tty` does not appear to work here - you must use the real
 TTY device path, as returned by the `tty` utility.
 
-## 3. Git's built-in [credential cache](https://git-scm.com/docs/git-credential-cache)
+## Git's built-in [credential cache](https://git-scm.com/docs/git-credential-cache)
+
+**Available on:** _Windows, macOS, Linux_
 
 ```shell
 export GCM_CREDENTIAL_STORE=cache
@@ -100,9 +185,10 @@ This credential store uses Git's built-in ephemeral
 [in-memory credential cache](https://git-scm.com/docs/git-credential-cache).
 This helps you reduce the number of times you have to authenticate but
 doesn't require storing credentials on persistent storage. It's good for
-scenarios like [Azure Cloud Shell](https://docs.microsoft.com/azure/cloud-shell/overview) or [AWS CloudShell](https://aws.amazon.com/cloudshell/), where you
-don't want to leave credentials on disk but also don't want to re-authenticate
-on every Git operation.
+scenarios like [Azure Cloud Shell](https://docs.microsoft.com/azure/cloud-shell/overview)
+or [AWS CloudShell](https://aws.amazon.com/cloudshell/), where you don't want to
+leave credentials on disk but also don't want to re-authenticate on every Git
+operation.
 
 By default, `git credential-cache` stores your credentials for 900 seconds.
 That, and any other
@@ -118,37 +204,36 @@ export GCM_CREDENTIAL_CACHE_OPTIONS="--timeout 300"
 git config --global credential.cacheOptions "--timeout 300"
 ```
 
-## 4. Plaintext files
+## Plaintext files
+
+**Available on:** _Windows, macOS, Linux_
+
+**:warning: This is not a secure method of credential storage!**
 
 ```shell
 export GCM_CREDENTIAL_STORE=plaintext
 # or
 git config --global credential.credentialStore plaintext
 ```
 
-**:warning: This is not a secure method of credential storage!**
-
 This credential store saves credentials to plaintext files in your file system.
-By default files are stored in `~/.gcm/store` but this can be configured using
-the environment variable `GCM_PLAINTEXT_STORE_PATH` environment variable.
+By default files are stored in `~/.gcm/store` or `%USERPROFILE%\.gcm\store`.
+This can be configured using the environment variable `GCM_PLAINTEXT_STORE_PATH`
+environment variable.
 
-If the directory does not exist is will be created.
+If the directory doesn't exist it will be created.
 
 On POSIX platforms the newly created store directory will have permissions set
 such that only the owner can `r`ead/`w`rite/e`x`ecute (`700` or `drwx---`).
 Permissions on existing directories will not be modified.
 
 ---
 
-<p align="center">
-
 :warning: **WARNING** :warning:
 
 **This storage mechanism is NOT secure!**
 
-**Secrets and credentials are stored in plaintext files _without any security_!<br/>
-Git Credential Manager Core takes no liability for the safety of these
-credentials.**
+**Secrets and credentials are stored in plaintext files _without any security_!**
 
 It is **HIGHLY RECOMMENDED** to always use one of the other credential store
 options above. This option is only provided for compatibility and use in
@@ -159,6 +244,4 @@ permissions on this directory such that no other users or applications can
 access files within. If possible, use a path that exists on an external volume
 that you take with you and use full-disk encryption.
 
-</p>
-
 ---