credentials

package module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 30, 2024 License: Apache-2.0 Imports: 4 Imported by: 5

README

Credential Management for oras-go

Build Status codecov Go Report Card Go Reference

banner

oras-credentials-go is a credential management library designed for oras-go. It supports reading, saving, and removing credentials from Docker configuration files and external credential stores that follow the Docker credential helper protocol.

[!IMPORTANT] The APIs previously located in this library have been moved to oras-go. As a result, these APIs are now deprecated and users should use the packages in oras-go instead.

This repository will now be used for developing experimental features scoped to credentials management. If any of these features are deemed stable and applicable to oras-go, they may be moved there in the future.

Versioning

The oras-credentials-go library follows Semantic Versioning, where breaking changes are reserved for MAJOR releases, and MINOR and PATCH releases must be 100% backwards compatible.

Docs

Code of Conduct

This project has adopted the CNCF Code of Conduct.

Documentation

Overview

Deprecated: This package is deprecated. The same functionality is now provided by oras.land/oras-go/v2/registry/remote/credentials.

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	// ErrPlaintextPutDisabled is returned by Put() when DisablePut is set
	// to true.
	//
	// Deprecated: This type is now simply [credentials.ErrPlaintextPutDisabled] of oras-go.
	//
	// [credentials.ErrPlaintextPutDisabled]: https://pkg.go.dev/oras.land/oras-go/v2/registry/remote/credentials#ErrPlaintextPutDisabled
	ErrPlaintextPutDisabled = credentials.ErrPlaintextPutDisabled
	// ErrBadCredentialFormat is returned by Put() when the credential format
	// is bad.
	//
	// Deprecated: This type is now simply [credentials.ErrBadCredentialFormat] of oras-go.
	//
	// [credentials.ErrBadCredentialFormat]: https://pkg.go.dev/oras.land/oras-go/v2/registry/remote/credentials#ErrBadCredentialFormat
	ErrBadCredentialFormat = credentials.ErrBadCredentialFormat
)
View Source
var ErrClientTypeUnsupported = credentials.ErrClientTypeUnsupported

ErrClientTypeUnsupported is thrown by Login() when the registry's client type is not supported.

Deprecated: This type is now simply credentials.ErrClientTypeUnsupported of oras-go.

Functions

func Credential deprecated

func Credential(store Store) func(context.Context, string) (auth.Credential, error)

Credential returns a Credential() function that can be used by auth.Client.

Deprecated: This funciton now simply calls credentials.Credential of oras-go.

Example
package main

import (
	"net/http"

	credentials "github.com/oras-project/oras-credentials-go"
	"oras.land/oras-go/v2/registry/remote/auth"
)

func main() {
	store, err := credentials.NewStore("example/path/config.json", credentials.StoreOptions{})
	if err != nil {
		panic(err)
	}

	client := auth.DefaultClient
	client.Credential = credentials.Credential(store)

	request, err := http.NewRequest(http.MethodGet, "localhost:5000", nil)
	if err != nil {
		panic(err)
	}

	_, err = client.Do(request)
	if err != nil {
		panic(err)
	}
}

func Login deprecated

func Login(ctx context.Context, store Store, reg *remote.Registry, cred auth.Credential) error

Login provides the login functionality with the given credentials. The target registry's client should be nil or of type *auth.Client. Login uses a client local to the function and will not modify the original client of the registry.

Deprecated: This funciton now simply calls credentials.Login of oras-go.

Example
package main

import (
	"context"
	"fmt"

	credentials "github.com/oras-project/oras-credentials-go"
	"oras.land/oras-go/v2/registry/remote"
	"oras.land/oras-go/v2/registry/remote/auth"
)

func main() {
	store, err := credentials.NewStore("example/path/config.json", credentials.StoreOptions{
		AllowPlaintextPut: true,
	})
	if err != nil {
		panic(err)
	}
	registry, err := remote.NewRegistry("localhost:5000")
	if err != nil {
		panic(err)
	}
	cred := auth.Credential{
		Username: "username-example",
		Password: "password-example",
	}
	err = credentials.Login(context.Background(), store, registry, cred)
	if err != nil {
		panic(err)
	}
	fmt.Println("Login succeeded")
}

func Logout deprecated

func Logout(ctx context.Context, store Store, registryName string) error

Logout provides the logout functionality given the registry name.

Deprecated: This funciton now simply calls credentials.Logout of oras-go.

Example
package main

import (
	"context"
	"fmt"

	credentials "github.com/oras-project/oras-credentials-go"
)

func main() {
	store, err := credentials.NewStore("example/path/config.json", credentials.StoreOptions{})
	if err != nil {
		panic(err)
	}
	err = credentials.Logout(context.Background(), store, "localhost:5000")
	if err != nil {
		panic(err)
	}
	fmt.Println("Logout succeeded")
}

func ServerAddressFromHostname deprecated added in v0.2.0

func ServerAddressFromHostname(hostname string) string

ServerAddressFromHostname maps a hostname to a server address, which is used as a key for credentials store. It is expected that the traffic targetting the host "registry-1.docker.io" will be redirected to "https://index.docker.io/v1/". See: https://github.com/moby/moby/blob/v24.0.2/registry/config.go#L25-L48

Deprecated: This funciton now simply calls credentials.ServerAddressFromHostname of oras-go.

func ServerAddressFromRegistry deprecated added in v0.2.0

func ServerAddressFromRegistry(registry string) string

ServerAddressFromRegistry maps a registry to a server address, which is used as a key for credentials store. The Docker CLI expects that the credentials of the registry 'docker.io' will be added under the key "https://index.docker.io/v1/". See: https://github.com/moby/moby/blob/v24.0.2/registry/config.go#L25-L48

Deprecated: This funciton now simply calls credentials.ServerAddressFromRegistry of oras-go.

Types

type DynamicStore deprecated added in v0.2.0

type DynamicStore = credentials.DynamicStore

DynamicStore dynamically determines which store to use based on the settings in the config file.

Deprecated: This type is now simply credentials.DynamicStore of oras-go.

func NewStore deprecated

func NewStore(configPath string, opts StoreOptions) (*DynamicStore, error)

NewStore returns a Store based on the given configuration file.

For Get(), Put() and Delete(), the returned Store will dynamically determine which underlying credentials store to use for the given server address. The underlying credentials store is determined in the following order:

  1. Native server-specific credential helper
  2. Native credentials store
  3. The plain-text config file itself

References:

Deprecated: This funciton now simply calls credentials.NewStore of oras-go.

Example
package main

import (
	"context"
	"fmt"

	credentials "github.com/oras-project/oras-credentials-go"
	"oras.land/oras-go/v2/registry/remote/auth"
)

func main() {
	// NewStore returns a Store based on the given configuration file. It will
	// automatically determine which Store (file store or native store) to use.
	// If the native store is not available, you can save your credentials in
	// the configuration file by specifying AllowPlaintextPut: true, but keep
	// in mind that this is an unsafe workaround.
	// See the documentation for details.
	store, err := credentials.NewStore("example/path/config.json", credentials.StoreOptions{
		AllowPlaintextPut: true,
	})
	if err != nil {
		panic(err)
	}

	ctx := context.Background()
	// save credentials into the store
	err = store.Put(ctx, "localhost:5000", auth.Credential{
		Username: "username-example",
		Password: "password-example",
	})
	if err != nil {
		panic(err)
	}

	// get credentials from the store
	cred, err := store.Get(ctx, "localhost:5000")
	if err != nil {
		panic(err)
	}
	fmt.Println(cred)

	// delete the credentials from the store
	err = store.Delete(ctx, "localhost:5000")
	if err != nil {
		panic(err)
	}
}

func NewStoreFromDocker deprecated

func NewStoreFromDocker(opts StoreOptions) (*DynamicStore, error)

NewStoreFromDocker returns a Store based on the default docker config file.

  • If the $DOCKER_CONFIG environment variable is set, $DOCKER_CONFIG/config.json will be used.
  • Otherwise, the default location $HOME/.docker/config.json will be used.

NewStoreFromDocker internally calls NewStore.

References:

Deprecated: This funciton now simply calls credentials.NewStoreFromDocker of oras-go.

Example
package main

import (
	"context"
	"fmt"

	credentials "github.com/oras-project/oras-credentials-go"
	"oras.land/oras-go/v2/registry/remote/auth"
)

func main() {
	ds, err := credentials.NewStoreFromDocker(credentials.StoreOptions{
		AllowPlaintextPut: true,
	})
	if err != nil {
		panic(err)
	}

	ctx := context.Background()
	// save credentials into the store
	err = ds.Put(ctx, "localhost:5000", auth.Credential{
		Username: "username-example",
		Password: "password-example",
	})
	if err != nil {
		panic(err)
	}

	// get credentials from the store
	cred, err := ds.Get(ctx, "localhost:5000")
	if err != nil {
		panic(err)
	}
	fmt.Println(cred)

	// delete the credentials from the store
	err = ds.Delete(ctx, "localhost:5000")
	if err != nil {
		panic(err)
	}
}

type FileStore deprecated

type FileStore = credentials.FileStore

FileStore implements a credentials store using the docker configuration file to keep the credentials in plain-text.

Reference: https://docs.docker.com/engine/reference/commandline/cli/#docker-cli-configuration-file-configjson-properties

Deprecated: This type is now simply credentials.FileStore of oras-go.

func NewFileStore deprecated

func NewFileStore(configPath string) (*FileStore, error)

NewFileStore creates a new file credentials store.

Reference: https://docs.docker.com/engine/reference/commandline/cli/#docker-cli-configuration-file-configjson-properties

Deprecated: This funciton now simply calls credentials.NewFileStore of oras-go.

Example
package main

import (
	"context"
	"fmt"

	credentials "github.com/oras-project/oras-credentials-go"
	"oras.land/oras-go/v2/registry/remote/auth"
)

func main() {
	fs, err := credentials.NewFileStore("example/path/config.json")
	if err != nil {
		panic(err)
	}

	ctx := context.Background()
	// save credentials into the store
	err = fs.Put(ctx, "localhost:5000", auth.Credential{
		Username: "username-example",
		Password: "password-example",
	})
	if err != nil {
		panic(err)
	}

	// get credentials from the store
	cred, err := fs.Get(ctx, "localhost:5000")
	if err != nil {
		panic(err)
	}
	fmt.Println(cred)

	// delete the credentials from the store
	err = fs.Delete(ctx, "localhost:5000")
	if err != nil {
		panic(err)
	}
}

type Store deprecated

type Store = credentials.Store

Store is the interface that any credentials store must implement.

Deprecated: This type is now simply credentials.Store of oras-go.

func NewDefaultNativeStore deprecated added in v0.2.0

func NewDefaultNativeStore() (Store, bool)

NewDefaultNativeStore returns a native store based on the platform-default docker credentials helper and a bool indicating if the native store is available.

  • Windows: "wincred"
  • Linux: "pass" or "secretservice"
  • macOS: "osxkeychain"

Reference:

Deprecated: This funciton now simply calls credentials.NewDefaultNativeStore of oras-go.

func NewMemoryStore deprecated added in v0.4.0

func NewMemoryStore() Store

NewMemoryStore creates a new in-memory credentials store.

Deprecated: This funciton now simply calls credentials.NewMemoryStore of oras-go.

func NewNativeStore deprecated

func NewNativeStore(helperSuffix string) Store

NewNativeStore creates a new native store that uses a remote helper program to manage credentials.

The argument of NewNativeStore can be the native keychains ("wincred" for Windows, "pass" for linux and "osxkeychain" for macOS), or any program that follows the docker-credentials-helper protocol.

Reference:

Deprecated: This funciton now simply calls credentials.NewNativeStore of oras-go.

Example
package main

import (
	"context"
	"fmt"

	credentials "github.com/oras-project/oras-credentials-go"
	"oras.land/oras-go/v2/registry/remote/auth"
)

func main() {
	ns := credentials.NewNativeStore("pass")

	ctx := context.Background()
	// save credentials into the store
	err := ns.Put(ctx, "localhost:5000", auth.Credential{
		Username: "username-example",
		Password: "password-example",
	})
	if err != nil {
		panic(err)
	}

	// get credentials from the store
	cred, err := ns.Get(ctx, "localhost:5000")
	if err != nil {
		panic(err)
	}
	fmt.Println(cred)

	// delete the credentials from the store
	err = ns.Delete(ctx, "localhost:5000")
	if err != nil {
		panic(err)
	}
}

func NewStoreWithFallbacks deprecated

func NewStoreWithFallbacks(primary Store, fallbacks ...Store) Store

NewStoreWithFallbacks returns a new store based on the given stores.

  • Get() searches the primary and the fallback stores for the credentials and returns when it finds the credentials in any of the stores.
  • Put() saves the credentials into the primary store.
  • Delete() deletes the credentials from the primary store.

Deprecated: This funciton now simply calls credentials.NewStoreWithFallbacks of oras-go.

Example (ConfigAsPrimaryStoreDockerAsFallback)
package main

import (
	"context"
	"fmt"

	credentials "github.com/oras-project/oras-credentials-go"
	"oras.land/oras-go/v2/registry/remote/auth"
)

func main() {
	primaryStore, err := credentials.NewStore("example/path/config.json", credentials.StoreOptions{
		AllowPlaintextPut: true,
	})
	if err != nil {
		panic(err)
	}
	fallbackStore, err := credentials.NewStoreFromDocker(credentials.StoreOptions{})
	sf := credentials.NewStoreWithFallbacks(primaryStore, fallbackStore)

	ctx := context.Background()
	// save credentials into the store
	err = sf.Put(ctx, "localhost:5000", auth.Credential{
		Username: "username-example",
		Password: "password-example",
	})
	if err != nil {
		panic(err)
	}

	// get credentials from the store
	cred, err := sf.Get(ctx, "localhost:5000")
	if err != nil {
		panic(err)
	}
	fmt.Println(cred)

	// delete the credentials from the store
	err = sf.Delete(ctx, "localhost:5000")
	if err != nil {
		panic(err)
	}
}

type StoreOptions deprecated

type StoreOptions = credentials.StoreOptions

StoreOptions provides options for NewStore.

Deprecated: This type is now simply credentials.StoreOptions of oras-go.

Directories

Path Synopsis
internal
Deprecated: This package is deprecated.
Deprecated: This package is deprecated.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL