tskagent

README

tskagent

This repository provides a tskagent ((T)ailscale (S)SH (K)ey Agent) library and program that implements the SSH key agent protocol hosting keys stored in setec.

To install the agent binary:

go install github.com/tailscale/tskagent/cmd/tskagent@latest

To run the agent, you must provide:

1. The URL of a setec server instance,
2. A non-empty secret name prefix to serve from, and
3. A path to a local socket to serve the agent protocol.

For example:

tskagent --server https://setec.example.com \
         --prefix prod/example/ssh-keys/ \
         --socket $HOME/.ssh/tskagent.sock

Once this is running, you can access the agent using the standard tools, for example you can list the available secrets by running:

export SSH_AUTH_SOCK="$HOME/.ssh/tskagent.sock"
ssh-add -L

The agent loads all the secrets matching the specified name prefix once at startup. The value of each secret must be a PEM-formatted private key. The agent logs and ignores any secrets that do not have this format.

By default, keys are loaded from setec only once when the agent starts up. Use --update to make it poll at the specified interval for new secret versions. The agent does not allow the client to add new secrets. It does allow the client to "delete" the local copy of a secret from the agent (ssh-add -d), but note that this only affects the agent's copy, it does not remove the key from setec.

Documentation

Overview

Package tskagent implements an SSH key agent backed by the setec service.

A Server implements an agent.Agent that serves SSH keys stored in the specified setec server. Each secret whose name matches a designated prefix and contains an SSH private key in OpenSSH PEM format is offered by the agent to callers on the local system.

Index

• type Config
• type Server
  • func NewServer(config Config) *Server
  • func (s *Server) Add(key agent.AddedKey) error
  • func (s *Server) List() ([]*agent.Key, error)
  • func (s *Server) Lock(passphrase []byte) error
  • func (s *Server) Remove(key ssh.PublicKey) error
  • func (s *Server) RemoveAll() error
  • func (s *Server) Serve(ctx context.Context, lst net.Listener)
  • func (s *Server) ServeOne(conn io.ReadWriter) error
  • func (s *Server) Sign(key ssh.PublicKey, data []byte) (*ssh.Signature, error)
  • func (s *Server) Signers() ([]ssh.Signer, error)
  • func (s *Server) Unlock(passphrase []byte) error
  • func (s *Server) Update(ctx context.Context) error

Types

type Config

type Config struct {
	// Client is the client for the secrets service. It must be set.
	Client setec.Client

	// Prefix is the secret name prefix to be served.  It must be non-empty.
	Prefix string

	// Logf, if set, is used to write logs. If nil, logs are discarded.
	Logf func(string, ...any)
}

Config carries the settings for a Server.

type Server

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

Server implements the SSH key agent server protocol. The caller must call agent.ServeAgent to expose the server to clients.

func NewServer

func NewServer(config Config) *Server

NewServer constructs a new Server that fetches SSH keys matching the specified configuration in setec.

The caller must call Server.Update at least once to initialize the list of keys available to the agent. Thereafter, the caller may call Update again as often as desired to update the list. The server does not automatically perform updates.

func (*Server) Add

func (s *Server) Add(key agent.AddedKey) error

Add implements part of the agent.Agent interface. This implementation does not support adding keys.

func (*Server) List

func (s *Server) List() ([]*agent.Key, error)

List implements part of the agent.Agent interface.

func (*Server) Lock

func (s *Server) Lock(passphrase []byte) error

Lock implements part of the agent.Agent interface.

func (*Server) Remove

func (s *Server) Remove(key ssh.PublicKey) error

Remove implements part of the agent.Agent interface.

This implementation only removes the key from the local list, it does not affect what is stored on the secrets server.

func (*Server) RemoveAll

func (s *Server) RemoveAll() error

RemoveAll implements part of the agent.Agent interface.

This implementation only removes keys from the local list, it does not affect what is stored on the secrets server.

func (*Server) Serve

func (s *Server) Serve(ctx context.Context, lst net.Listener)

Serve accepts connections from lst and serve the agent to each in its own goroutine. It runs until lst closes or ctx ends.

func (*Server) ServeOne

func (s *Server) ServeOne(conn io.ReadWriter) error

ServeOne serves the agent to the specified connection. It is safe to call ServeOne concurrently from multiple goroutines with separate connections, including while Serve is running.

func (*Server) Sign

func (s *Server) Sign(key ssh.PublicKey, data []byte) (*ssh.Signature, error)

Sign implements part of the agent.Agent interface.

func (*Server) Signers

func (s *Server) Signers() ([]ssh.Signer, error)

Signers implements part of the agent.Agent interface.

func (*Server) Unlock

func (s *Server) Unlock(passphrase []byte) error

Unlock implements part of the agent.Agent interface.

func (*Server) Update

func (s *Server) Update(ctx context.Context) error

Update attempts to update the list of keys from the secrets service. It is safe to call Update concurrently with client access. In case of error, the existing list of keys is not modified.