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
- Variables
- func VDLReadRpcMessage(dec vdl.Decoder, x *RpcMessage) error
- type AgentClientMethods
- type AgentClientStub
- type AgentNotifyWhenChangedClientCall
- type AgentNotifyWhenChangedClientStream
- type AgentNotifyWhenChangedServerCall
- type AgentNotifyWhenChangedServerCallStub
- type AgentNotifyWhenChangedServerStream
- type AgentServerMethods
- type AgentServerStub
- type AgentServerStubMethods
- type ConnInfo
- type Principal
- type RpcMessage
- type RpcMessageReq
- type RpcMessageResp
- type RpcRequest
- type RpcResponse
Constants ¶
const PrincipalHandleByteSize = sha512.Size
Variables ¶
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 ¶
func (s *AgentNotifyWhenChangedServerCallStub) Init(call rpc.StreamServerCall)
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 ¶
func (ConnInfo) VDLReflect ¶
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)
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)
type RpcRequest ¶
func (RpcRequest) VDLIsZero ¶
func (x RpcRequest) VDLIsZero() bool
func (RpcRequest) VDLReflect ¶
func (RpcRequest) VDLReflect(struct { Name string `vdl:"v.io/x/ref/services/agent.RpcRequest"` })
type RpcResponse ¶
func (RpcResponse) VDLIsZero ¶
func (x RpcResponse) VDLIsZero() bool
func (RpcResponse) VDLReflect ¶
func (RpcResponse) VDLReflect(struct { Name string `vdl:"v.io/x/ref/services/agent.RpcResponse"` })
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. |