Sebastiaan van Stijn
e1d4c012bc
* Fix storing URLs without scheme If secrets are stored without specifying a scheme (https://), the keychain-helper would interpret the hostname as _path_, causing lookup of secrets to fail. This patch makes sure that a scheme is added (if missing). If no scheme is specified, https:// is used as a default. Signed-off-by: Sebastiaan van Stijn <github@gone.nl> * Have pre go1.8 compiler able to compile Signed-off-by: Tibor Vass <teabee89@gmail.com> * Fix URL parsing with port and no scheme Signed-off-by: Nassim 'Nass' Eddequiouaq <eddequiouaq.nassim@gmail.com> * Improve parseURL comment Signed-off-by: Nassim 'Nass' Eddequiouaq <eddequiouaq.nassim@gmail.com>
Introduction
docker-credential-helpers is a suite of programs to use native stores to keep Docker credentials safe.
Installation
Go to the Releases page and download the binary that works better for you. Put that binary in your $PATH, so Docker can find it.
Building from scratch
The programs in this repository are written with the Go programming language. These instructions assume that you have previous knowledge about the language and you have it installed in your machine.
1 - Download the source and put it in your $GOPATH with go get.
$ go get github.com/docker/docker-credential-helpers
2 - Use make to build the program you want. That will leave any executable in the bin directory inside the repository.
$ cd $GOPATH/docker/docker-credentials-helpers
$ make osxkeychain
3 - Put that binary in your $PATH, so Docker can find it.
Usage
With the Docker Engine
Set the credsStore option in your .docker/config.json file with the suffix of the program you want to use. For instance, set it to osxkeychain if you want to use docker-credential-osxkeychain.
{
"credsStore": "osxkeychain"
}
With other command line applications
The sub-package client includes functions to call external programs from your own command line applications.
There are three things you need to know if you need to interact with a helper:
- The name of the program to execute, for instance
docker-credential-osxkeychain. - The server address to identify the credentials, for instance
https://example.com. - The username and secret to store, when you want to store credentials.
You can see examples of each function in the client documentation.
Available programs
- osxkeychain: Provides a helper to use the OS X keychain as credentials store.
- secretservice: Provides a helper to use the D-Bus secret service as credentials store.
- wincred: Provides a helper to use Windows credentials manager as store.
Development
A credential helper can be any program that can read values from the standard input. We use the first argument in the command line to differentiate the kind of command to execute. There are four valid values:
store: Adds credentials to the keychain. The payload in the standard input is a JSON document withServerURL,UsernameandSecret.get: Retrieves credentials from the keychain. The payload in the standard input is the raw value for theServerURL.erase: Removes credentials from the keychain. The payload in the standard input is the raw value for theServerURL.list: Lists stored credentials. There is no standard input payload.
This repository also includes libraries to implement new credentials programs in Go. Adding a new helper program is pretty easy. You can see how the OS X keychain helper works in the osxkeychain directory.
- Implement the interface
credentials.HelperinYOUR_PACKAGE/YOUR_PACKAGE_$GOOS.go - Create a main program in
YOUR_PACKAGE/cmd/main_$GOOS.go. - Add make tasks to build your program and run tests.
License
MIT. See LICENSE for more information.