Add linux kernel keyring based credential helper

Implement kernel kerying based credential helper for storing and
retrieving secrets.

Signed-off-by: Alakesh Haloi <[email protected]>
Signed-off-by: Sebastiaan van Stijn <[email protected]>

Author: alakesh

Dockerfile

@@ -109,6 +109,10 @@ RUN --mount=type=bind,target=. \
   make build-pass build-secretservice PACKAGE=$PACKAGE VERSION=$(cat /tmp/.version) REVISION=$(cat /tmp/.revision) DESTDIR=/out
   xx-verify /out/docker-credential-pass
   xx-verify /out/docker-credential-secretservice
+
+  # keyctl credential helper
+  xx-go build -ldflags "$(cat /tmp/.ldflags)" -o /out/docker-credential-keyctl ./keyctl/cmd/
+  xx-verify /out/docker-credential-keyctl
 EOT
 
 FROM base AS build-darwin

Makefile

@@ -27,11 +27,12 @@ build-%: # build, can be one of build-osxkeychain build-pass build-secretservice
 	go build -trimpath -ldflags="$(GO_LDFLAGS) -X ${GO_PKG}/credentials.Name=docker-credential-$*" -o "$(DESTDIR)/docker-credential-$*" ./$*/cmd/
 
 # aliases for build-* targets
-.PHONY: osxkeychain secretservice pass wincred
+.PHONY: osxkeychain secretservice pass wincred keyctl
 osxkeychain: build-osxkeychain
 secretservice: build-secretservice
 pass: build-pass
 wincred: build-wincred
+keyctl: build-keyctl
 
 .PHONY: cross
 cross: # cross build all supported credential helpers

README.md

@@ -84,12 +84,15 @@ You can see examples of each function in the [client](https://godoc.org/github.c
 2. secretservice: Provides a helper to use the D-Bus secret service as credentials store.
 3. wincred: Provides a helper to use Windows credentials manager as store.
 4. pass: Provides a helper to use `pass` as credentials store.
+5. keyctl: Provides a kernel keyring based helper as credential store. It is a purely non-file based credential store.
 
 #### Note
 
 `pass` needs to be configured for `docker-credential-pass` to work properly.
 It must be initialized with a `gpg2` key ID. Make sure your GPG key exists is in `gpg2` keyring as `pass` uses `gpg2` instead of the regular `gpg`.
 
+`keyctl` does not need any configuration except that kernel should be compiled with CONFIG_KEYS enabled, which is default in most distro kernels.
+
 ## 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:

go.mod

@@ -2,6 +2,10 @@ module github.com/docker/docker-credential-helpers
 
 go 1.19
 
-require github.com/danieljoos/wincred v1.2.1
+require (
+	github.com/danieljoos/wincred v1.2.1
+	github.com/jsipprell/keyctl v1.0.0
+	github.com/pkg/errors v0.9.1
+)
 
 require golang.org/x/sys v0.15.0 // indirect

go.sum

@@ -1,6 +1,10 @@
 github.com/danieljoos/wincred v1.2.1 h1:dl9cBrupW8+r5250DYkYxocLeZ1Y4vB1kxgtjxw8GQs=
 github.com/danieljoos/wincred v1.2.1/go.mod h1:uGaFL9fDn3OLTvzCGulzE+SzjEe5NGlh5FdCcyfPwps=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/jsipprell/keyctl v1.0.0 h1:eMMJGk3UEsCXQegACLlfIjnfPlYHV61qfGXZ9/axBn4=
+github.com/jsipprell/keyctl v1.0.0/go.mod h1:64s6WpBtruURX3w8W/vhWj1/uh+nOm7vUXSJlK5+KMs=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/stretchr/objx v0.5.0 h1:1zr/of2m5FGMsad5YfcqgdqdWrIhu+EBEJRhR1U7z/c=
 github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=

keyctl/cmd/main.go

@@ -0,0 +1,10 @@
+package main
+
+import (
+	"github.com/docker/docker-credential-helpers/credentials"
+	"github.com/docker/docker-credential-helpers/keyctl"
+)
+
+func main() {
+	credentials.Serve(keyctl.Keyctl{})
+}

keyctl/keyctl.go

@@ -0,0 +1,250 @@
+// Package keyctl implements a `keyctl` based credential helper. Passwords are stored
+// in linux kernel keyring.
+package keyctl
+
+import (
+	"bytes"
+	"encoding/base64"
+	"fmt"
+	"os"
+	"os/exec"
+	"strconv"
+	"strings"
+
+	"github.com/docker/docker-credential-helpers/credentials"
+	"github.com/jsipprell/keyctl"
+	"github.com/pkg/errors"
+)
+
+// Keyctl based credential helper looks for a default keyring inside
+// session keyring. It does all operations inside the default keyring
+
+const defaultKeyringName string = "keyctlCredsStore"
+const persistent int = 1
+
+// Keyctl handles secrets using Linux Kernel keyring mechanism
+type Keyctl struct{}
+
+func (k Keyctl) createDefaultPersistentKeyring() (string, error) {
+	/* Create default persistent keyring. If the keyring for the user
+	 * already exists, then it returns the id of the existing keyring
+	 */
+	var errout, out bytes.Buffer
+	uid := os.Getuid()
+	cmd := exec.Command("keyctl", "get_persistent", "@u", strconv.Itoa(uid))
+	cmd.Stderr = &errout
+	cmd.Stdout = &out
+	err := cmd.Run()
+	if err != nil {
+		return "", errors.Wrapf(err, "cannot run keyctl command to create persistent keyring %+v: %s", err, errout.String())
+	}
+	persistentKeyringID := out.String()
+	if err != nil {
+		return "", errors.Wrapf(err, "cannot create or read persistent keyring %+v", err)
+	}
+	return persistentKeyringID, nil
+}
+
+func (k Keyctl) getDefaultCredsStoreFromPersistent() (keyctl.NamedKeyring, error) {
+	var out, errout bytes.Buffer
+	persistentKeyringID, err := k.createDefaultPersistentKeyring()
+	if err != nil {
+		return nil, errors.Wrap(err, "default persistent keyring cannot be created")
+	}
+
+	defaultSessionKeyring, err := keyctl.SessionKeyring()
+	if err != nil {
+		return nil, errors.New("errors getting session keyring")
+	}
+
+	defaultKeyring, err := keyctl.OpenKeyring(defaultSessionKeyring, defaultKeyringName)
+	/* if already does not exist we create */
+	if err != nil || defaultKeyring == nil {
+		cmd := exec.Command("keyctl", "newring", defaultKeyringName, strings.TrimSuffix(persistentKeyringID, "\n"))
+		cmd.Stdout = &out
+		cmd.Stderr = &errout
+		err := cmd.Run()
+		if err != nil {
+			return nil, errors.Wrapf(err, "cannot run keyctl command to created credstore keyring %s %s %s", cmd.String(), errout.String(), out.String())
+		}
+	}
+	/* Search for it again and return the default keyring*/
+	defaultKeyring, err = keyctl.OpenKeyring(defaultSessionKeyring, defaultKeyringName)
+	if err != nil {
+		return nil, errors.Wrap(err, "failed to lookup default session keyring")
+	}
+
+	return defaultKeyring, nil
+}
+
+// getDefaultCredsStore is a helper function to get the default credsStore keyring
+func (k Keyctl) getDefaultCredsStore() (keyctl.NamedKeyring, error) {
+	if persistent == 1 {
+		return k.getDefaultCredsStoreFromPersistent()
+	}
+	defaultSessionKeyring, err := keyctl.SessionKeyring()
+	if err != nil {
+		return nil, errors.Wrap(err, "error getting session keyring")
+	}
+
+	defaultKeyring, err := keyctl.OpenKeyring(defaultSessionKeyring, defaultKeyringName)
+	if err != nil || defaultKeyring == nil {
+		if defaultKeyring == nil {
+			defaultKeyring, err = keyctl.CreateKeyring(defaultSessionKeyring, defaultKeyringName)
+			if err != nil {
+				return nil, errors.Wrap(err, "failed to create default credsStore keyring")
+			}
+		}
+	}
+
+	if defaultKeyring == nil {
+		return nil, errors.Wrap(errors.New(""), " nil credstore")
+	}
+
+	return defaultKeyring, nil
+}
+
+// Add adds new credentials to the keychain.
+func (k Keyctl) Add(creds *credentials.Credentials) error {
+	defaultKeyring, err := k.getDefaultCredsStore()
+	if err != nil || defaultKeyring == nil {
+		return errors.Wrapf(err, "failed to create credsStore entry for %s", creds.ServerURL)
+	}
+
+	// create a child keyring under default for given url
+	encoded := base64.URLEncoding.EncodeToString([]byte(strings.TrimSuffix(creds.ServerURL, "\n")))
+	urlKeyring, err := keyctl.CreateKeyring(defaultKeyring, encoded)
+	if err != nil {
+		return errors.Wrapf(err, "failed to create keyring for %s", creds.ServerURL)
+	}
+
+	_, err = urlKeyring.Add(creds.Username, []byte(creds.Secret))
+	if err != nil {
+		return errors.Wrapf(err, "failed to add creds to keryring for %s with error: %+v", creds.ServerURL, err)
+	}
+	return err
+}
+
+// searchHelper function searches for an url inside the default keyring.
+func (k Keyctl) searchHelper(serverURL string) (keyctl.NamedKeyring, string, error) {
+	defaultKeyring, err := k.getDefaultCredsStore()
+	if err != nil || defaultKeyring == nil {
+		return nil, "", fmt.Errorf("searchHelper failed: cannot read defaultCredsStore")
+	}
+
+	encoded := base64.URLEncoding.EncodeToString([]byte(strings.TrimSuffix(serverURL, "\n")))
+	urlKeyring, err := keyctl.OpenKeyring(defaultKeyring, encoded)
+	if err != nil {
+		return nil, "", fmt.Errorf("error in reading credsStore for url %s", serverURL)
+	}
+	if urlKeyring == nil {
+		return nil, "", fmt.Errorf("credsStore entry for suplied url %s not found", serverURL)
+	}
+
+	refs, err := keyctl.ListKeyring(urlKeyring)
+	if err != nil {
+		return nil, "", fmt.Errorf("key for server url not found")
+	}
+	if len(refs) < 1 {
+		return nil, "", fmt.Errorf("no keys in keyring %s", urlKeyring.Name())
+	}
+
+	obj := refs[0]
+	id, err := obj.Get()
+	if err != nil {
+		return nil, "", fmt.Errorf("key for server url not found")
+	}
+
+	info, err := id.Info()
+	if err != nil {
+		return nil, "", fmt.Errorf("cannot read info for url key")
+	}
+
+	return urlKeyring, info.Name, err
+}
+
+// Get returns the username and secret to use for a given registry server URL.
+func (k Keyctl) Get(serverURL string) (string, string, error) {
+	if serverURL == "" {
+		return "", "", errors.New("missing server url")
+	}
+
+	serverURL = strings.TrimSuffix(serverURL, "\n")
+	urlKeyring, searchData, err := k.searchHelper(serverURL)
+	if err != nil {
+		return "", "", errors.Wrapf(err, "url not found by searchHelper:  %s err: %v", serverURL, err)
+	}
+	key, err := urlKeyring.Search(searchData)
+	if err != nil {
+		return "", "", errors.Wrapf(err, "url not found in %+v", urlKeyring)
+	}
+	secret, err := key.Get()
+	if err != nil {
+		return "", "", errors.Wrapf(err, "failed to read credentials for %s:%s", serverURL, searchData)
+	}
+
+	return searchData, string(secret), nil
+}
+
+// Delete removes credentials from the store.
+func (k Keyctl) Delete(serverURL string) error {
+	serverURL = strings.TrimSuffix(serverURL, "\n")
+	urlKeyring, searchData, err := k.searchHelper(serverURL)
+	if err != nil {
+		return errors.Wrapf(err, "cannot find server url %s", serverURL)
+	}
+
+	key, err := urlKeyring.Search(searchData)
+	if err != nil {
+		return err
+	}
+
+	err = key.Unlink()
+	if err != nil {
+		return err
+	}
+
+	refs, err := keyctl.ListKeyring(urlKeyring)
+	if err != nil {
+		fmt.Printf("cannot list keyring %s", urlKeyring.Name())
+	}
+	if len(refs) == 0 {
+		keyctl.UnlinkKeyring(urlKeyring)
+	} else {
+		return errors.Wrapf(err, "Canot remove keyring as its not empty %s", urlKeyring.Name())
+	}
+
+	return err
+}
+
+// List returns the stored URLs and corresponding usernames for a given credentials label
+func (k Keyctl) List() (map[string]string, error) {
+	defaultKeyring, err := k.getDefaultCredsStore()
+	if err != nil || defaultKeyring == nil {
+		return nil, errors.Wrap(err, "List() failed: cannot read default credStore")
+	}
+
+	resp := map[string]string{}
+
+	refs, err := keyctl.ListKeyring(defaultKeyring)
+	if err != nil {
+		return nil, err
+	}
+
+	for _, r := range refs {
+		id, _ := r.Get()
+		info, _ := id.Info()
+		url, _ := base64.URLEncoding.DecodeString(info.Name)
+
+		key, _ := keyctl.OpenKeyring(defaultKeyring, info.Name)
+		innerRefs, _ := keyctl.ListKeyring(key)
+
+		if len(innerRefs) < 1 {
+			continue
+		}
+		k, _ := innerRefs[0].Get()
+		i, _ := k.Info()
+		resp[string(url)] = i.Name
+	}
+	return resp, nil
+}