yubiagent

Documentation

Overview

Package yubiagent implements a protocol to communicate with YubiKey via a forwarded ssh-agent. It provides a client agent and a server agent. The server side wraps the common YubiKey operations in customized ssh-agent protocol. The client follows this protocol to manipulate YubiKey.

Index

• Constants
• func ServeAgent(agent YubiAgent, c io.ReadWriter) error
• type YubiAgent
  • func NewClient(address string) (YubiAgent, error)
  • func NewClientFromConn(c net.Conn) (YubiAgent, error)
  • func NewServer(address string, remote bool) (YubiAgent, error)

Constants

const (
	// AgentMessageAddHardCert extends the SSH agent protocol numbers for the YubiKey's capability
	// to add hardware certificate.
	AgentMessageAddHardCert = 31
	// AgentMessageListSlots extends the SSH agent protocol numbers for the YubiKey's capability to
	// list keys in slots.
	AgentMessageListSlots = 32
	// AgentMessageReadSlot extends the SSH agent protocol numbers for the YubiKey's capability to
	// read key in the slot.
	AgentMessageReadSlot = 33
	// AgentMessageAttestSlot extends the SSH agent protocol numbers for the YubiKey's capability to
	// attest the key in slot.
	AgentMessageAttestSlot = 34
	// AgentMessageWait extends the SSH agent protocol numbers for the YubiKey's capability to wait
	// for the specified operation finished.
	AgentMessageWait = 35
)

Following messages are the ssh agent protocol number, which are used as the tags of sshtype in a yubiagent request. These numbers extend the SSH agent protocol.

const (
	// AgentMessageAddSmartcardKey is the SSH agent protocol numbers described in https://datatracker.ietf.org/doc/html/draft-miller-ssh-agent-01#rfc.section.7.1.
	// We use AgentMessageAddSmartcardKeyConstrained instead to add key lifetime constrains.
	AgentMessageAddSmartcardKey = 20
	// AgentMessageRemoveSmartcardKey is the SSH agent protocol numbers described in https://datatracker.ietf.org/doc/html/draft-miller-ssh-agent-01#rfc.section.7.1.
	AgentMessageRemoveSmartcardKey = 21
	// AgentMessageAddSmartcardKeyConstrained is the SSH agent protocol numbers described in https://datatracker.ietf.org/doc/html/draft-miller-ssh-agent-01#rfc.section.7.1.
	AgentMessageAddSmartcardKeyConstrained = 26
)

Following messages define the operations to add/remove smartcard keys to/from the ssh agent.

const (
	// AgentMessageRequestV1Identities helps backward compatibility for the request keys.
	AgentMessageRequestV1Identities = 1

	// AgentMessageRequestIdentities is the SSH agent protocol number for agent.List.
	AgentMessageRequestIdentities = 11
	// AgentMessageSignRequest is the SSH agent protocol number for agent.Sign.
	AgentMessageSignRequest = 13
	// AgentMessageAddIdentity is the SSH agent protocol number for agent.Add.
	AgentMessageAddIdentity = 17
	// AgentMessageRemoveIdentity is the SSH agent protocol number for agent.Remove.
	AgentMessageRemoveIdentity = 18
	// AgentMessageRemoveAllIdentities is the SSH agent protocol number for agent.RemoveAll.
	AgentMessageRemoveAllIdentities = 19
	// AgentMessageAddIDConstrained is the SSH agent protocol number for agent.Add.
	AgentMessageAddIDConstrained = 25

	// AgentMessageLock is the SSH agent protocol number for agent.Lock.
	AgentMessageLock = 22
	// AgentMessageUnlock is the SSH agent protocol number for agent.Unlock.
	AgentMessageUnlock = 23
)

A request with any following ssh agent protocol numbers require a forwarder (see: struct forwarder) to forward net.Conn from YSSHRA, yubiagent to SSH agent. See [PROTOCOL.agent], section 3: https://datatracker.ietf.org/doc/html/draft-miller-ssh-agent-00

Functions

func ServeAgent

func ServeAgent(agent YubiAgent, c io.ReadWriter) error

ServeAgent uses an agent (usually a server object) to serve the connection c.

Types

type YubiAgent

type YubiAgent interface {
	shimagent.ShimAgent

	// ListSlots lists all the used slots in YubiKey.
	ListSlots() (slots []string, err error)

	// ReadSlot reads x509 certificate in PEM format from the specified slot.
	ReadSlot(slot string) (cert *x509.Certificate, err error)

	// AttestSlot signs the public key of the specified slot with the private key of "f9" slot and
	// returns the resulting attestation certificate in PEM format, which can be verified later on.
	// More details: https://developers.yubico.com/yubico-piv-tool/Attestation.html
	AttestSlot(slot string) (cert *x509.Certificate, err error)

	// AddSmartcardKey adds the specified smartcard to the agent.
	AddSmartcardKey(readerId string, pin []byte, lifetime time.Duration, confirmBeforeUse bool) error

	// RemoveSmartcardKey removes the specified smartcard from the agent.
	RemoveSmartcardKey(readerId string, pin []byte) error
}

YubiAgent is an interface that extends the functionality of the ShimAgent interface in agent/shimagent package, which also extends the native ssh agent.

func NewClient

func NewClient(address string) (YubiAgent, error)

NewClient returns a new YubiAgent client object. The parameter address is used to connect to a YubiAgent server. The definition of address depends on OS. For Darwin and Linux, address is a unix socket. For Windows, address is a named pipe.

func NewClientFromConn

func NewClientFromConn(c net.Conn) (YubiAgent, error)

NewClientFromConn returns a new YubiAgent client object. This function can be used when we have an in-memory network connection net.Pipe() or an SSH agent connection.

func NewServer

func NewServer(address string, remote bool) (YubiAgent, error)

NewServer will create a new server that implements yubiagent.YubiAgent interface. The parameter address is used to connect to a real ssh-agent. The definition of address depends on OS. For Darwin and Linux, address is a unix socket. For Windows, address is a named pipe.