agent

package
v0.0.0-...-ba1c585 Latest Latest
Warning

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

Go to latest
Published: Jun 29, 2017 License: BSD-3-Clause Imports: 9 Imported by: 0

Documentation

Overview

Package agent defines an interface to keep a private key in memory, and for clients to have access to the private key.

Protocol

The agent starts processes with the VEYRON_AGENT_FD set to one end of a unix domain socket. To connect to the agent, a client should create a unix domain socket pair. Then send one end of the socket to the agent with 1 byte of data. The agent will then serve the Agent service on the received socket, using SecurityNone.

The agent also supports an optional mode where it can manage multiple principals. Typically this is only used by Device Manager. In this mode, VEYRON_AGENT_FD will be 3, and there will be another socket at fd 4. Creating a new principal is similar to connecting to to agent: create a socket pair and send one end on fd 4 with 1 byte of data. Set the data to 1 to request the principal only be stored in memory. The agent will create a new principal and respond with a principal handle on fd 4. To connect using a previously created principal, create a socket pair and send one end with the principal handle as data on fd 4. The agent will not send a response on fd 4. In either, you can use the normal process to connect to an agent over the other end of the pair. Typically you would pass the other end to a child process and set VEYRON_AGENT_FD so it knows to connect.

The protocol also has limited support for caching: A client can request notification when any other client modifies the principal so it can flush the cache. See NotifyWhenChanged for details.

Index

Constants

View Source
const PrincipalHandleByteSize = sha512.Size

Variables

View Source
var AgentDesc rpc.InterfaceDesc = descAgent

AgentDesc describes the Agent interface.

Functions

func VDLReadRpcMessage

func VDLReadRpcMessage(dec vdl.Decoder, x *RpcMessage) error

Types

type AgentClientMethods

type AgentClientMethods interface {
	Bless(_ *context.T, key []byte, wit security.Blessings, extension string, caveat security.Caveat, additionalCaveats []security.Caveat, _ ...rpc.CallOpt) (security.Blessings, error)
	BlessSelf(_ *context.T, name string, caveats []security.Caveat, _ ...rpc.CallOpt) (security.Blessings, error)
	Sign(_ *context.T, message []byte, _ ...rpc.CallOpt) (security.Signature, error)
	MintDischarge(_ *context.T, forCaveat security.Caveat, caveatOnDischarge security.Caveat, additionalCaveatsOnDischarge []security.Caveat, _ ...rpc.CallOpt) (security.Discharge, error)
	PublicKey(*context.T, ...rpc.CallOpt) ([]byte, error)
	BlessingStoreSet(_ *context.T, blessings security.Blessings, forPeers security.BlessingPattern, _ ...rpc.CallOpt) (security.Blessings, error)
	BlessingStoreForPeer(_ *context.T, peerBlessings []string, _ ...rpc.CallOpt) (security.Blessings, error)
	BlessingStoreSetDefault(_ *context.T, blessings security.Blessings, _ ...rpc.CallOpt) error
	BlessingStoreDefault(*context.T, ...rpc.CallOpt) (security.Blessings, error)
	BlessingStorePeerBlessings(*context.T, ...rpc.CallOpt) (map[security.BlessingPattern]security.Blessings, error)
	BlessingStoreDebugString(*context.T, ...rpc.CallOpt) (string, error)
	BlessingStoreCacheDischarge(_ *context.T, discharge security.Discharge, caveat security.Caveat, impetus security.DischargeImpetus, _ ...rpc.CallOpt) error
	BlessingStoreClearDischarges(_ *context.T, discharges []security.Discharge, _ ...rpc.CallOpt) error
	BlessingStoreDischarge(_ *context.T, caveat security.Caveat, impetus security.DischargeImpetus, _ ...rpc.CallOpt) (wd security.Discharge, _ error)
	BlessingRootsAdd(_ *context.T, root []byte, pattern security.BlessingPattern, _ ...rpc.CallOpt) error
	BlessingRootsRecognized(_ *context.T, root []byte, blessing string, _ ...rpc.CallOpt) error
	BlessingRootsDump(*context.T, ...rpc.CallOpt) (map[security.BlessingPattern][][]byte, error)
	BlessingRootsDebugString(*context.T, ...rpc.CallOpt) (string, error)
	// Clients using caching should call NotifyWhenChanged upon connecting to
	// the server. The server will stream back values whenever the client should
	// flush the cache. The streamed value is arbitrary, simply flush whenever
	// recieving a new item.
	NotifyWhenChanged(*context.T, ...rpc.CallOpt) (AgentNotifyWhenChangedClientCall, error)
}

AgentClientMethods is the client interface containing Agent methods.

type AgentClientStub

type AgentClientStub interface {
	AgentClientMethods
	rpc.UniversalServiceMethods
}

AgentClientStub adds universal methods to AgentClientMethods.

func AgentClient

func AgentClient(name string) AgentClientStub

AgentClient returns a client stub for Agent.

type AgentNotifyWhenChangedClientCall

type AgentNotifyWhenChangedClientCall interface {
	AgentNotifyWhenChangedClientStream
	// Finish blocks until the server is done, and returns the positional return
	// values for call.
	//
	// Finish returns immediately if the call has been canceled; depending on the
	// timing the output could either be an error signaling cancelation, or the
	// valid positional return values from the server.
	//
	// Calling Finish is mandatory for releasing stream resources, unless the call
	// has been canceled or any of the other methods return an error.  Finish should
	// be called at most once.
	Finish() error
}

AgentNotifyWhenChangedClientCall represents the call returned from Agent.NotifyWhenChanged.

type AgentNotifyWhenChangedClientStream

type AgentNotifyWhenChangedClientStream interface {
	// RecvStream returns the receiver side of the Agent.NotifyWhenChanged client stream.
	RecvStream() interface {
		// Advance stages an item so that it may be retrieved via Value.  Returns
		// true iff there is an item to retrieve.  Advance must be called before
		// Value is called.  May block if an item is not available.
		Advance() bool
		// Value returns the item that was staged by Advance.  May panic if Advance
		// returned false or was not called.  Never blocks.
		Value() bool
		// Err returns any error encountered by Advance.  Never blocks.
		Err() error
	}
}

AgentNotifyWhenChangedClientStream is the client stream for Agent.NotifyWhenChanged.

type AgentNotifyWhenChangedServerCall

type AgentNotifyWhenChangedServerCall interface {
	rpc.ServerCall
	AgentNotifyWhenChangedServerStream
}

AgentNotifyWhenChangedServerCall represents the context passed to Agent.NotifyWhenChanged.

type AgentNotifyWhenChangedServerCallStub

type AgentNotifyWhenChangedServerCallStub struct {
	rpc.StreamServerCall
}

AgentNotifyWhenChangedServerCallStub is a wrapper that converts rpc.StreamServerCall into a typesafe stub that implements AgentNotifyWhenChangedServerCall.

func (*AgentNotifyWhenChangedServerCallStub) Init

Init initializes AgentNotifyWhenChangedServerCallStub from rpc.StreamServerCall.

func (*AgentNotifyWhenChangedServerCallStub) SendStream

func (s *AgentNotifyWhenChangedServerCallStub) SendStream() interface {
	Send(item bool) error
}

SendStream returns the send side of the Agent.NotifyWhenChanged server stream.

type AgentNotifyWhenChangedServerStream

type AgentNotifyWhenChangedServerStream interface {
	// SendStream returns the send side of the Agent.NotifyWhenChanged server stream.
	SendStream() interface {
		// Send places the item onto the output stream.  Returns errors encountered
		// while sending.  Blocks if there is no buffer space; will unblock when
		// buffer space is available.
		Send(item bool) error
	}
}

AgentNotifyWhenChangedServerStream is the server stream for Agent.NotifyWhenChanged.

type AgentServerMethods

type AgentServerMethods interface {
	Bless(_ *context.T, _ rpc.ServerCall, key []byte, wit security.Blessings, extension string, caveat security.Caveat, additionalCaveats []security.Caveat) (security.Blessings, error)
	BlessSelf(_ *context.T, _ rpc.ServerCall, name string, caveats []security.Caveat) (security.Blessings, error)
	Sign(_ *context.T, _ rpc.ServerCall, message []byte) (security.Signature, error)
	MintDischarge(_ *context.T, _ rpc.ServerCall, forCaveat security.Caveat, caveatOnDischarge security.Caveat, additionalCaveatsOnDischarge []security.Caveat) (security.Discharge, error)
	PublicKey(*context.T, rpc.ServerCall) ([]byte, error)
	BlessingStoreSet(_ *context.T, _ rpc.ServerCall, blessings security.Blessings, forPeers security.BlessingPattern) (security.Blessings, error)
	BlessingStoreForPeer(_ *context.T, _ rpc.ServerCall, peerBlessings []string) (security.Blessings, error)
	BlessingStoreSetDefault(_ *context.T, _ rpc.ServerCall, blessings security.Blessings) error
	BlessingStoreDefault(*context.T, rpc.ServerCall) (security.Blessings, error)
	BlessingStorePeerBlessings(*context.T, rpc.ServerCall) (map[security.BlessingPattern]security.Blessings, error)
	BlessingStoreDebugString(*context.T, rpc.ServerCall) (string, error)
	BlessingStoreCacheDischarge(_ *context.T, _ rpc.ServerCall, discharge security.Discharge, caveat security.Caveat, impetus security.DischargeImpetus) error
	BlessingStoreClearDischarges(_ *context.T, _ rpc.ServerCall, discharges []security.Discharge) error
	BlessingStoreDischarge(_ *context.T, _ rpc.ServerCall, caveat security.Caveat, impetus security.DischargeImpetus) (wd security.Discharge, _ error)
	BlessingRootsAdd(_ *context.T, _ rpc.ServerCall, root []byte, pattern security.BlessingPattern) error
	BlessingRootsRecognized(_ *context.T, _ rpc.ServerCall, root []byte, blessing string) error
	BlessingRootsDump(*context.T, rpc.ServerCall) (map[security.BlessingPattern][][]byte, error)
	BlessingRootsDebugString(*context.T, rpc.ServerCall) (string, error)
	// Clients using caching should call NotifyWhenChanged upon connecting to
	// the server. The server will stream back values whenever the client should
	// flush the cache. The streamed value is arbitrary, simply flush whenever
	// recieving a new item.
	NotifyWhenChanged(*context.T, AgentNotifyWhenChangedServerCall) error
}

AgentServerMethods is the interface a server writer implements for Agent.

type AgentServerStub

type AgentServerStub interface {
	AgentServerStubMethods
	// Describe the Agent interfaces.
	Describe__() []rpc.InterfaceDesc
}

AgentServerStub adds universal methods to AgentServerStubMethods.

func AgentServer

func AgentServer(impl AgentServerMethods) AgentServerStub

AgentServer returns a server stub for Agent. It converts an implementation of AgentServerMethods into an object that may be used by rpc.Server.

type AgentServerStubMethods

type AgentServerStubMethods interface {
	Bless(_ *context.T, _ rpc.ServerCall, key []byte, wit security.Blessings, extension string, caveat security.Caveat, additionalCaveats []security.Caveat) (security.Blessings, error)
	BlessSelf(_ *context.T, _ rpc.ServerCall, name string, caveats []security.Caveat) (security.Blessings, error)
	Sign(_ *context.T, _ rpc.ServerCall, message []byte) (security.Signature, error)
	MintDischarge(_ *context.T, _ rpc.ServerCall, forCaveat security.Caveat, caveatOnDischarge security.Caveat, additionalCaveatsOnDischarge []security.Caveat) (security.Discharge, error)
	PublicKey(*context.T, rpc.ServerCall) ([]byte, error)
	BlessingStoreSet(_ *context.T, _ rpc.ServerCall, blessings security.Blessings, forPeers security.BlessingPattern) (security.Blessings, error)
	BlessingStoreForPeer(_ *context.T, _ rpc.ServerCall, peerBlessings []string) (security.Blessings, error)
	BlessingStoreSetDefault(_ *context.T, _ rpc.ServerCall, blessings security.Blessings) error
	BlessingStoreDefault(*context.T, rpc.ServerCall) (security.Blessings, error)
	BlessingStorePeerBlessings(*context.T, rpc.ServerCall) (map[security.BlessingPattern]security.Blessings, error)
	BlessingStoreDebugString(*context.T, rpc.ServerCall) (string, error)
	BlessingStoreCacheDischarge(_ *context.T, _ rpc.ServerCall, discharge security.Discharge, caveat security.Caveat, impetus security.DischargeImpetus) error
	BlessingStoreClearDischarges(_ *context.T, _ rpc.ServerCall, discharges []security.Discharge) error
	BlessingStoreDischarge(_ *context.T, _ rpc.ServerCall, caveat security.Caveat, impetus security.DischargeImpetus) (wd security.Discharge, _ error)
	BlessingRootsAdd(_ *context.T, _ rpc.ServerCall, root []byte, pattern security.BlessingPattern) error
	BlessingRootsRecognized(_ *context.T, _ rpc.ServerCall, root []byte, blessing string) error
	BlessingRootsDump(*context.T, rpc.ServerCall) (map[security.BlessingPattern][][]byte, error)
	BlessingRootsDebugString(*context.T, rpc.ServerCall) (string, error)
	// Clients using caching should call NotifyWhenChanged upon connecting to
	// the server. The server will stream back values whenever the client should
	// flush the cache. The streamed value is arbitrary, simply flush whenever
	// recieving a new item.
	NotifyWhenChanged(*context.T, *AgentNotifyWhenChangedServerCallStub) error
}

AgentServerStubMethods is the server interface containing Agent methods, as expected by rpc.Server. The only difference between this interface and AgentServerMethods is the streaming methods.

type ConnInfo

type ConnInfo struct {
	MinVersion int32
	MaxVersion int32
}

func (ConnInfo) VDLIsZero

func (x ConnInfo) VDLIsZero() bool

func (*ConnInfo) VDLRead

func (x *ConnInfo) VDLRead(dec vdl.Decoder) error

func (ConnInfo) VDLReflect

func (ConnInfo) VDLReflect(struct {
	Name string `vdl:"v.io/x/ref/services/agent.ConnInfo"`
})

func (ConnInfo) VDLWrite

func (x ConnInfo) VDLWrite(enc vdl.Encoder) error

type Principal

type Principal interface {
	security.Principal
	io.Closer
}

type RpcMessage

type RpcMessage interface {
	// Index returns the field index.
	Index() int
	// Interface returns the field value as an interface.
	Interface() interface{}
	// Name returns the field name.
	Name() string
	// VDLReflect describes the RpcMessage union type.
	VDLReflect(__RpcMessageReflect)
	VDLIsZero() bool
	VDLWrite(vdl.Encoder) error
}

RpcMessage represents any single field of the RpcMessage union type.

type RpcMessageReq

type RpcMessageReq struct{ Value RpcRequest }

RpcMessageReq represents field Req of the RpcMessage union type.

func (RpcMessageReq) Index

func (x RpcMessageReq) Index() int

func (RpcMessageReq) Interface

func (x RpcMessageReq) Interface() interface{}

func (RpcMessageReq) Name

func (x RpcMessageReq) Name() string

func (RpcMessageReq) VDLIsZero

func (x RpcMessageReq) VDLIsZero() bool

func (RpcMessageReq) VDLReflect

func (x RpcMessageReq) VDLReflect(__RpcMessageReflect)

func (RpcMessageReq) VDLWrite

func (x RpcMessageReq) VDLWrite(enc vdl.Encoder) error

type RpcMessageResp

type RpcMessageResp struct{ Value RpcResponse }

RpcMessageResp represents field Resp of the RpcMessage union type.

func (RpcMessageResp) Index

func (x RpcMessageResp) Index() int

func (RpcMessageResp) Interface

func (x RpcMessageResp) Interface() interface{}

func (RpcMessageResp) Name

func (x RpcMessageResp) Name() string

func (RpcMessageResp) VDLIsZero

func (x RpcMessageResp) VDLIsZero() bool

func (RpcMessageResp) VDLReflect

func (x RpcMessageResp) VDLReflect(__RpcMessageReflect)

func (RpcMessageResp) VDLWrite

func (x RpcMessageResp) VDLWrite(enc vdl.Encoder) error

type RpcRequest

type RpcRequest struct {
	Id      uint64
	Method  string
	NumArgs uint32
}

func (RpcRequest) VDLIsZero

func (x RpcRequest) VDLIsZero() bool

func (*RpcRequest) VDLRead

func (x *RpcRequest) VDLRead(dec vdl.Decoder) error

func (RpcRequest) VDLReflect

func (RpcRequest) VDLReflect(struct {
	Name string `vdl:"v.io/x/ref/services/agent.RpcRequest"`
})

func (RpcRequest) VDLWrite

func (x RpcRequest) VDLWrite(enc vdl.Encoder) error

type RpcResponse

type RpcResponse struct {
	Id      uint64
	Err     error
	NumArgs uint32
}

func (RpcResponse) VDLIsZero

func (x RpcResponse) VDLIsZero() bool

func (*RpcResponse) VDLRead

func (x *RpcResponse) VDLRead(dec vdl.Decoder) error

func (RpcResponse) VDLReflect

func (RpcResponse) VDLReflect(struct {
	Name string `vdl:"v.io/x/ref/services/agent.RpcResponse"`
})

func (RpcResponse) VDLWrite

func (x RpcResponse) VDLWrite(enc vdl.Encoder) error

Directories

Path Synopsis
Package agentlib provides ways to create Principals that are backed by the security agent.
Package agentlib provides ways to create Principals that are backed by the security agent.
Command gcreds runs a command with Google Cloud Blessings.
Command gcreds runs a command with Google Cloud Blessings.
internal
constants
Package constants holds constants shared by client and server.
Package constants holds constants shared by client and server.
ipc
Package ipc implements a simple IPC system based on VOM.
Package ipc implements a simple IPC system based on VOM.
launcher
Package launcher contains utilities to launch v23agentd.
Package launcher contains utilities to launch v23agentd.
lock
Package lock provides a lock object to synchronize access to a directory among multiple processes.
Package lock provides a lock object to synchronize access to a directory among multiple processes.
lockfile
Package lockfile provides methods to associate process ids (PIDs) with a file.
Package lockfile provides methods to associate process ids (PIDs) with a file.
lockutil
Package lockutil contains utilities for building file locks.
Package lockutil contains utilities for building file locks.
lru
Package lru implements a Least-Recently-Used (LRU) cache of objects keyed by a string.
Package lru implements a Least-Recently-Used (LRU) cache of objects keyed by a string.
pingpong
Command pingpong runs a pingpong client or server.
Command pingpong runs a pingpong client or server.
test_principal
Command test_principal runs tests against a principal.
Command test_principal runs tests against a principal.
version
Package version provides versioning for the agent.
Package version provides versioning for the agent.
Command pod_agentd runs a security agent daemon, which holds a private key in memory and makes it available to the kubernetes pod in which it is running.
Command pod_agentd runs a security agent daemon, which holds a private key in memory and makes it available to the kubernetes pod in which it is running.
Package server contains utilities for serving a principal using a socket-based IPC system.
Package server contains utilities for serving a principal using a socket-based IPC system.
Command v23agentd manages the security agent daemon, which holds the private key, blessings and recognized roots of a principal in memory and makes the principal available to other processes.
Command v23agentd manages the security agent daemon, which holds the private key, blessings and recognized roots of a principal in memory and makes the principal available to other processes.
Command vbecome executes commands with a derived Vanadium principal.
Command vbecome executes commands with a derived Vanadium principal.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL