credential

README

credential

Package credential provides a simple and secure interface for retrieving secrets from systemd's credential management system. It enables Go applications to safely access sensitive information such as cryptographic keys, certificates, passwords, and identity data in systemd-managed services.

Installation

To install credential and use it in your project, run:

go get git.sr.ht/~jamesponddotco/credential-go@latest

You'll want to ensure your system meets these requirements:

• Go 1.23 or later.
• systemd-based Linux distribution.
• Proper systemd service configuration with credentials.

Documentation

• Please see the Go reference documentation for more information about the package.
• Refer to systemd credentials documentation for more details on its credential management system.

Usage

To use credential, your systemd service unit must be configured with credentials, as the CREDENTIALS_DIRECTORY environment variable required by the package is set by systemd when running as a service with credentials configured.

Example systemd service configuration:

[Unit]
Description=My Application Service

[Service]
ExecStart=/usr/local/bin/myapp
LoadCredential=myapp-database-password:/path/to/secret/file
PrivateMounts=yes

[Install]
WantedBy=multi-user.target

Here's a basic example of how to use the package:

package main

import (
	"fmt"
	"log"

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

func main() {
	// Open the credential store with your application's name as the prefix.
	store, err := credential.Open("myapp")
	if err != nil {
		log.Fatal(err)
	}

	// Retrieve a secret from the store.
	secret, err := store.Get("database-password")
	if err != nil {
		log.Fatal(err)
	}

	// Print the secret or do something else with it.
	fmt.Println("Database password:", secret)
}

Contributing

Anyone can help make credential better. Send patches on the mailing list and report bugs on the issue tracker.

You must sign-off your work using git commit --signoff. Follow the Linux kernel developer's certificate of origin for more details.

All contributions are made under the MIT License.

Resources

The following resources are available:

• Package documentation.
• Support and general discussions.
• Patches and development related questions.
• Instructions on how to prepare patches.
• Feature requests and bug reports.

---

Released under the MIT License.

Documentation

Overview

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.