client

package
v1.4.1 Latest Latest
Warning

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

 Go to latest Published: May 14, 2026 License: Apache-2.0 Imports: 38 Imported by: 0

Documentation

Overview

Package client implements the Knox CLI client commands.

Package client implements the Knox CLI client commands.

Package client implements the Knox CLI client commands.

Index

Constants

View Source 
const (
	DefaultUsageLine             = "login [username]"
	DefaultShortDescription      = "login as user and save authentication data"
	DefaultLongDescriptionFormat = `` /* 353-byte string literal not displayed */

)
View Source 
const DefaultTokenFileLocation = ".knox_token"

Variables

View Source 
var ErrTimeout = errors.New("timeout waiting on lock to become available")

ErrTimeout is returned when we cannot obtain an exclusive lock on the key file.

View Source 
var Version = "devel"

Version represents the compiled version of the client binary. It can be overridden at compile time with: `go build -ldflags "-X github.com/hazayan/knox/client.Version=1.2.3" github.com/hazayan/knox/cmd/dev_client` In the above example, knox version would give you `1.2.3`. By default, the version is `devel`.

Functions

func GetBackoffDuration 

func GetBackoffDuration(attempt int) time.Duration

GetBackoffDuration returns a time duration to sleep based on the attempt #.

func GetVersion 

func GetVersion() string

GetVersion exposes the current client version.

func NewMockKeyVersion 

func NewMockKeyVersion(keydata []byte, status types.VersionStatus) types.KeyVersion

NewMockKeyVersion creates a Knox types.KeyVersion to be used for testing.

func Register 

func Register(keyID string) ([]byte, error)

Register registers the given keyName with knox. If the operation fails, it returns an error.

Types

type APIClient 

type APIClient interface {
	GetKey(keyID string) (*types.Key, error)
	CreateKey(keyID string, data []byte, acl types.ACL) (uint64, error)
	GetKeys(keys map[string]string) ([]string, error)
	DeleteKey(keyID string) error
	GetACL(keyID string) (*types.ACL, error)
	PutAccess(keyID string, acl ...types.Access) error
	AddVersion(keyID string, data []byte) (uint64, error)
	UpdateVersion(keyID, versionID string, status types.VersionStatus) error
	CacheGetKey(keyID string) (*types.Key, error)
	NetworkGetKey(keyID string) (*types.Key, error)
	GetKeyWithStatus(keyID string, status types.VersionStatus) (*types.Key, error)
	CacheGetKeyWithStatus(keyID string, status types.VersionStatus) (*types.Key, error)
	NetworkGetKeyWithStatus(keyID string, status types.VersionStatus) (*types.Key, error)
}

APIClient is an interface that talks to the knox server for key management.

func NewClient 

func NewClient(host string, client HTTP, authHandlers []AuthHandler, keyFolder, version string) APIClient

NewClient creates a new client to connect to talk to Knox. NOTE: passing multiple authHandlers can cause severe performance issues, use with caution.

type AuthHandler 

type AuthHandler func() (authToken string, authType string, clientOverride HTTP)

AuthHandler represents an authentication method, clientOverride is optional and allows using a custom client for the request. clientOverride is useful when using multiple TLS certs as different auth handlers.

type Client 

type Client interface {
	// GetPrimary returns the primary key version for the knox key.
	// This should be used for sending relationships like signing, encrypting, or api secrets
	GetPrimary() string
	// GetActive returns all of the active key versions for the knox key.
	// This should be used for receiving relationships like verifying or decrypting.
	GetActive() []string
	// GetKeyObject returns the full key object, including versions, ACLs, and other attributes.
	GetKeyObject() types.Key
}

Client is an interface for interacting with a specific knox key.

func NewFileClient 

func NewFileClient(keyID string) (Client, error)

NewFileClient creates a file watcher knox client for the keyID given (it refreshes every ten seconds). This client calls `knox register` to cache the key locally on the file system.

func NewMock 

func NewMock(primary string, active []string) Client

NewMock is a knox Client to be used for testing.

type Command 

type Command struct {
	// Run contains the command execution logic.
	// If Run is nil, the command is not runnable.
	Run func(cmd *Command, args []string) *ErrorStatus

	// Flag is a flag set for parsing command-line flags.
	Flag flag.FlagSet

	// UsageLine is the one-line usage message.
	// The first word in the usage line is taken as the command name.
	UsageLine string

	// Short is the short description shown in 'knox help' output.
	Short string

	// Long is the long message shown in 'knox help <this-command>' output.
	Long string
}

Command represents a CLI command with its execution logic and metadata.

func NewLoginCommand 

func NewLoginCommand(
	oauthTokenEndpoint string,
	oauthClientID string,
	tokenFileLocation string,
) *Command

NewLoginCommand creates a new login command with the specified OAuth configuration.

func (*Command) Name 

func (c *Command) Name() string

Name returns the command's name: the first word in the usage line.

func (*Command) Runnable 

func (c *Command) Runnable() bool

Runnable reports whether the command can be run; otherwise it is a documentation pseudo-command.

func (*Command) Usage 

func (c *Command) Usage()

Usage prints the command's usage information to standard output.

type ErrorStatus 

type ErrorStatus struct {
	// contains filtered or unexported fields
}

ErrorStatus represents the result of executing a command. It contains both the error information and whether it's a server-side error.

func (*ErrorStatus) Error 

func (e *ErrorStatus) Error() string

Error returns the error message.

func (*ErrorStatus) ShouldExit 

func (e *ErrorStatus) ShouldExit() bool

ShouldExit indicates whether the error should cause the program to exit. This is typically true for server errors and false for client/user errors.

type HTTP 

type HTTP interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTP is an interface for making HTTP requests in the Knox client.

type HTTPClient 

type HTTPClient struct {
	// KeyFolder is the location of cached keys on the file system. If empty, does not check for cached keys.
	KeyFolder string
	// Client is the http client for making network calls
	UncachedClient *UncachedHTTPClient
}

HTTPClient is a client that uses HTTP to talk to Knox.

func MockClient 

func MockClient(host, keyFolder string) *HTTPClient

MockClient builds a client for testing that uses a custom certificate pool.

func (*HTTPClient) AddVersion 

func (c *HTTPClient) AddVersion(keyID string, data []byte) (uint64, error)

AddVersion adds a key version to a specific key.

func (*HTTPClient) CacheGetKey 

func (c *HTTPClient) CacheGetKey(keyID string) (*types.Key, error)

CacheGetKey gets the key from file system cache.

func (*HTTPClient) CacheGetKeyWithStatus 

func (c *HTTPClient) CacheGetKeyWithStatus(keyID string, status types.VersionStatus) (*types.Key, error)

CacheGetKeyWithStatus gets the key with status from file system cache.

func (*HTTPClient) CreateKey 

func (c *HTTPClient) CreateKey(keyID string, data []byte, acl types.ACL) (uint64, error)

CreateKey creates a knox key with given keyID data and types.ACL.

func (HTTPClient) DeleteKey 

func (c HTTPClient) DeleteKey(keyID string) error

DeleteKey deletes a key from Knox.

func (*HTTPClient) GetACL 

func (c *HTTPClient) GetACL(keyID string) (*types.ACL, error)

GetACL gets a knox key by keyID.

func (*HTTPClient) GetKey 

func (c *HTTPClient) GetKey(keyID string) (*types.Key, error)

GetKey gets a knox key by keyID.

func (*HTTPClient) GetKeyWithStatus 

func (c *HTTPClient) GetKeyWithStatus(keyID string, status types.VersionStatus) (*types.Key, error)

GetKeyWithStatus gets a knox key by keyID and status (leverages cache).

func (*HTTPClient) GetKeys 

func (c *HTTPClient) GetKeys(keys map[string]string) ([]string, error)

GetKeys gets all Knox (if empty map) or gets all keys in map that do not match key version hash.

func (*HTTPClient) NetworkGetKey 

func (c *HTTPClient) NetworkGetKey(keyID string) (*types.Key, error)

NetworkGetKey gets a knox key by keyID and only uses network without the caches.

func (*HTTPClient) NetworkGetKeyWithStatus 

func (c *HTTPClient) NetworkGetKeyWithStatus(keyID string, status types.VersionStatus) (*types.Key, error)

NetworkGetKeyWithStatus gets a knox key by keyID and given version status (always calls network).

func (*HTTPClient) PutAccess 

func (c *HTTPClient) PutAccess(keyID string, a ...types.Access) error

PutAccess will add an types.ACL rule to a specific key.

func (*HTTPClient) UpdateVersion 

func (c *HTTPClient) UpdateVersion(keyID, versionID string, status types.VersionStatus) error

UpdateVersion either promotes or demotes a specific key version.

type Keys 

type Keys interface {
	Get() ([]string, error)
	Add([]string) error
	Overwrite([]string) error
	Remove([]string) error
	Lock() error
	Unlock() error
}

Keys are an interface for storing a list of key ids (for use with the register file to provide locks).

func NewKeysFile 

func NewKeysFile(fn string) Keys

NewKeysFile takes in a filename and outputs an implementation of the Keys interface.

type KeysFile 

type KeysFile struct {
	// contains filtered or unexported fields
}

KeysFile is an implementation of Keys based on the file system for the register file.

func (*KeysFile) Add 

func (k *KeysFile) Add(ks []string) error

Add will add the key IDs to the list. It expects Lock to have been called.

func (*KeysFile) Get 

func (k *KeysFile) Get() ([]string, error)

Get will get the list of key ids. It expects Lock to have been called.

func (*KeysFile) Lock 

func (k *KeysFile) Lock() error

Lock performs the nonblocking syscall lock and retries until the global timeout is met.

func (*KeysFile) Overwrite 

func (k *KeysFile) Overwrite(ks []string) error

Overwrite deletes all existing values in the key list and writes the input. It expects Lock to have been called.

func (*KeysFile) Remove 

func (k *KeysFile) Remove(ks []string) error

Remove will remove the input key ids from the list. It expects Lock to have been called.

func (*KeysFile) Unlock 

func (k *KeysFile) Unlock() error

Unlock performs the nonblocking syscall unlock and retries until the global timeout is met.

type UncachedHTTPClient 

type UncachedHTTPClient struct {
	// Host is used as the host for http connections
	Host string
	// AuthHandlers contains a list of auth handlers which return the authorization string for authenticating to knox. Users should be prefixed by 0u, machines by 0m. On fail, return empty string.
	AuthHandlers []AuthHandler
	// DefaultClient is the http client for making network calls
	DefaultClient HTTP
	// Version is the current client version, useful for debugging and sent as a header
	Version string
}

UncachedHTTPClient is a client that uses HTTP to talk to Knox without caching.

func NewUncachedClient 

func NewUncachedClient(host string, client HTTP, authHandlers []AuthHandler, version string) *UncachedHTTPClient

NewUncachedClient creates a new uncached client to connect to talk to Knox. NOTE: passing multiple authHandlers can cause severe performance issues, use with caution.

func (*UncachedHTTPClient) AddVersion 

func (c *UncachedHTTPClient) AddVersion(keyID string, data []byte) (uint64, error)

AddVersion adds a key version to a specific key.

func (*UncachedHTTPClient) CacheGetKey 

func (c *UncachedHTTPClient) CacheGetKey(keyID string) (*types.Key, error)

CacheGetKey acts same as NetworkGetKey for UncachedHTTPClient.

func (*UncachedHTTPClient) CacheGetKeyWithStatus 

func (c *UncachedHTTPClient) CacheGetKeyWithStatus(keyID string, status types.VersionStatus) (*types.Key, error)

CacheGetKeyWithStatus acts same as NetworkGetKeyWithStatus for UncachedHTTPClient.

func (*UncachedHTTPClient) CreateKey 

func (c *UncachedHTTPClient) CreateKey(keyID string, data []byte, acl types.ACL) (uint64, error)

CreateKey creates a knox key with given keyID data and types.ACL.

func (UncachedHTTPClient) DeleteKey 

func (c UncachedHTTPClient) DeleteKey(keyID string) error

DeleteKey deletes a key from Knox.

func (*UncachedHTTPClient) GetACL 

func (c *UncachedHTTPClient) GetACL(keyID string) (*types.ACL, error)

GetACL gets a knox key by keyID.

func (*UncachedHTTPClient) GetKey 

func (c *UncachedHTTPClient) GetKey(keyID string) (*types.Key, error)

GetKey gets a knox key by keyID.

func (*UncachedHTTPClient) GetKeyWithStatus 

func (c *UncachedHTTPClient) GetKeyWithStatus(keyID string, status types.VersionStatus) (*types.Key, error)

GetKeyWithStatus gets a knox key by keyID and status (no cache).

func (*UncachedHTTPClient) GetKeys 

func (c *UncachedHTTPClient) GetKeys(keys map[string]string) ([]string, error)

GetKeys gets all Knox (if empty map) or gets all keys in map that do not match key version hash.

func (*UncachedHTTPClient) NetworkGetKey 

func (c *UncachedHTTPClient) NetworkGetKey(keyID string) (*types.Key, error)

NetworkGetKey gets a knox key by keyID and only uses network without the caches.

func (*UncachedHTTPClient) NetworkGetKeyWithStatus 

func (c *UncachedHTTPClient) NetworkGetKeyWithStatus(keyID string, status types.VersionStatus) (*types.Key, error)

NetworkGetKeyWithStatus gets a knox key by keyID and given version status (always calls network).

func (*UncachedHTTPClient) PutAccess 

func (c *UncachedHTTPClient) PutAccess(keyID string, a ...types.Access) error

PutAccess will add an types.ACL rule to a specific key.

func (*UncachedHTTPClient) UpdateVersion 

func (c *UncachedHTTPClient) UpdateVersion(keyID, versionID string, status types.VersionStatus) error

UpdateVersion either promotes or demotes a specific key version.

type VisibilityParams 

type VisibilityParams struct {
	// Logf is a function for logging informational messages.
	Logf func(format string, v ...any)

	// Errorf is a function for logging error messages.
	Errorf func(format string, v ...any)

	// SummaryMetrics is a function for reporting summary metrics.
	SummaryMetrics func(metrics map[string]uint64)

	// InvokeMetrics is a function for reporting invoke metrics.
	InvokeMetrics func(metrics map[string]string)

	// GetKeyMetrics is a function for reporting get key metrics.
	GetKeyMetrics func(metrics map[string]string)
}

VisibilityParams contains parameters for controlling command visibility and logging.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.