package credential

import "git.sr.ht/~jamesponddotco/credential-go"

Package credential provides a simple interface for retrieving secrets from systemd's credential management system, which allows for secure storage and retrieval of sensitive information.

Credential names must follow these rules: - Cannot be empty. - Cannot contain path separators (/ or \). - Cannot contain path traversal sequences (..).

Each credential is limited to 1MB in size, as enforced by systemd.

Example usage:

// Open the credential store with a prefix.
store, err := credential.Open("myapp")
if err != nil {
    log.Fatal(err)
}

// Retrieve a secret.
secret, err := store.Get("database-password")
if err != nil {
    if errors.Is(err, credential.ErrInvalidName) {
        log.Fatal("Invalid credential name")
    }
    log.Fatal(err)
}

fmt.Println("Database password:", secret)

The package is designed to work with systemd's credential system and expects the CREDENTIALS_DIRECTORY environment variable to be set. When running as a systemd service, credentials are typically stored in /run/credentials.

Credential names are prefixed with the application name to prevent naming conflicts. For example, if the prefix is "myapp" and the credential name is "database-password", the actual file will be named "myapp-database-password".

Index ¶

• Constants
• type Store
• func Open(prefix string) (Store, error)
• func (s Store) Get(name string) (string, error)
• func (s Store) GetBytes(name string) ([]byte, error)

Constants ¶

const (
	// ErrDirectoryUnset indicates that the CREDENTIALS_DIRECTORY environment
	// variable is not set. This typically means the program is not running as a
	// systemd service unit with credentials configured.
	ErrDirectoryUnset xerrors.Error = "CREDENTIALS_DIRECTORY environment variable not set; is this a systemd service?"

	// ErrDirectoryAccess indicates that the credentials directory could not be
	// accessed by whatever reason, likely a permission issue.
	ErrDirectoryAccess xerrors.Error = "failed to access credentials directory"

	// ErrMissingPrefix indicates that the credential prefix was not provided. A
	// prefix is required to namespace credentials and prevent naming conflicts.
	ErrMissingPrefix xerrors.Error = "credentials prefix cannot be empty"

	// ErrInvalidName indicates that the requested credential name is invalid.
	// Names cannot be empty or contain path separators.
	ErrInvalidName xerrors.Error = "credential name cannot be empty or contain path separators"

	// ErrCredentialValue indicates that the value of the credential could not
	// be read for whatever reason.
	ErrCredentialValue xerrors.Error = "failed to read credential's value"
)

const EnvironmentVariableName = "CREDENTIALS_DIRECTORY"

EnvironmentVariableName is the name of the environment variable that contains the path to the directory where credentials are stored.

Types ¶

type Store ¶

type Store struct {
	// Path is the absolute path to the credentials' directory.
	Path string

	// Prefix is the namespace prefix for credentials.
	Prefix string
}

Store represents the directory where secrets are stored by systemd.

func Open ¶

func Open(prefix string) (Store, error)

Open returns a new Store instance using the specified Prefix. It returns an error if the CREDENTIALS_DIRECTORY environment variable is not set or if the directory is not accessible.

func (Store) Get ¶

func (s Store) Get(name string) (string, error)

Get retrieves the credential with the given name as a string. It returns an error if the credential doesn't exist or is not accessible.

func (Store) GetBytes ¶

func (s Store) GetBytes(name string) ([]byte, error)

GetBytes retrieves the credential with the given name as a byte slice. It returns an error if the credential doesn't exist or is not accessible.

Source Files ¶

doc.go store.go