README
¶
Store Keychain
Keychain integrates with the OS keystore. It supports Linux, macOS and Windows
and can be used directly with keychain.New.
- Linux uses the
org.freedesktop.secretsAPI. - macOS uses the macOS Keychain services API.
- Windows uses the Windows Credential Manager API
For more design implementation see ../docs/keychain/design.md.
Quickstart
import "github.com/docker/secrets-engine/store/keychain"
func main() {
kc, err := keychain.New(
"service-group",
"service-name",
func() *mocks.MockCredential {
return &mocks.MockCredential{}
},
)
}
Secrets
The keychain assumes that any secret stored would conform to the store.Secret
interface. This allows the keychain to store secrets of any type and leaves
it up to the implementer to decide how they would like their secret parsed.
Example CLI
The keychain package also contains an example CLI tool to test out how a real
application might interact with the host keychain.
You can build the CLI by running go build inside the store/ root directory.
$ go build -o keychain-cli ./keychain/cmd/
$ ./keychain-cli
Documentation
¶
Overview ¶
The keychain package for Linux uses the org.freedesktop.secret service API over dbus. For more information on the Secret Service API, see https://specifications.freedesktop.org/secret-service-spec/latest/index.html.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoDefaultCollection = errors.New("no default keychain collection available")
ErrNoDefaultCollection is returned when the secret service has no usable default collection (no 'login' collection and no collection assigned to the 'default' alias). This typically happens on headless hosts where the keyring has not been initialized.
NOTE: this condition is currently specific to the Linux keyring (the freedesktop Secret Service). macOS and Windows have no equivalent "default collection" concept, so the keychain store never returns this error on those platforms. The sentinel is nonetheless declared here, in the cross-platform file (rather than the Linux-specific one), so that platform-agnostic callers can reference it on every platform without build tags. On non-Linux platforms it simply never matches.
It is exported so callers can use errors.Is to detect the absence of usable keychain infrastructure and fall back gracefully, rather than relying on fragile error message comparisons.
Functions ¶
func New ¶
func New[T store.Secret](serviceGroup, serviceName string, factory store.Factory[T], opts ...Option) (store.Store, error)
New creates a new keychain store.
It takes ServiceGroup and ServiceName and a [Factory] as input.
A ServiceGroup is added to an item stored by the keychain under the item's attributes and label. Many applications can share the same serviceGroup.
On macOS it is important that the service group matches the Keychain Access Groups. This prevents access from other applications not inside the Keychain Access group. https://developer.apple.com/documentation/security/sharing-access-to-keychain-items-among-a-collection-of-apps#Set-your-apps-access-groups
On Linux the service group is added to the attributes of a secret to tag the item. The secrets service API does not have the concept of a scoped item per application inside the collection. Thus, adding a service group does not prevent other applications from accessing the secret.
A ServiceName is a unique name of the application storing credentials, it is important to keep the service name unchanged once the service has stored credentials. Changing the service name can be done, but would require migrating existing credentials.
[Factory] is a function used to instantiate new secrets of type T.
Types ¶
type DarwinOptions ¶ added in v0.0.17
type DarwinOptions optionFunc[darwinOptions]
func WithUseDataProtectionKeychain ¶ added in v0.0.17
func WithUseDataProtectionKeychain() DarwinOptions
WithUseDataProtectionKeychain forces the use of entitlements to share credentials stored in the keychain between applications
type Option ¶ added in v0.0.17
type Option interface {
// contains filtered or unexported methods
}
func WithDarwinOptions ¶ added in v0.0.17
func WithDarwinOptions(opt DarwinOptions) Option
Source Files
Directories