lrpc

Overview ¶

Package lrpc defines various interfaces and types used in communication with Centrify Client

Porting to different operating systems ¶

The current implementation is implemented as tested in Linux. System dependent code are implemented in the files peer_linux.go and network_linux.go; and you need to provide equivalent functionalities for other platforms.

File session_linux.go

 This file implements all OS dependent functions defined in the SessionCtxt interface.  You need to implement the factory function
 NewSessionCtxt() and the following functions in SessionCtxt interface:

	// IsPrivileged() returns true if the peer process runs as privileged process.
	// In *nix, this means the effective UID is root (0)
	// In windows, this means the owner of process has local admin right
	IsPrivileged() (bool, error)

	// GetProcessID() returns the process ID of the peer process
	GetProcessID() (int32, error)

	// GetProgram() returns the name of program executable that the peer process is running with
	GetProgram() (string, error)

 Note that SessionCtxtBase is a helper struct that provides OS independent support for SessionCtxt.  More importantly, it implements the
 Get() and Set() methods for managing session related information.

File network_linux.go

// This file implements the OS-dependent code for listening and connecting to the service endpoint.  You need to implement the following functions:
//
// StartListener is OS-dependent function to establish an internal listener.
// Input parameter:
// endpoint (string):          The name of the endpoint
// acl (AccessControlLevel):   The access control level to start listening
//
// Return values:
// net.Listener:	network listener object established.
// error
//
// Note:
// This function should remove the endpoint if it already exists.

func StartListener(endpoint string, acl AccessControlLevel) (net.Listener, error)

// ConnectToServer is OS-dependent code for connecting to an internal endpoint.
// It is used by a RPC client.
//
// Input parameters:
// endpoint (string):          The endpoint to connect to.
// acl (AccessControlLevel):   The ACL for establishing the listener
//
// Return values:
// net.Conn:   The established network connection.
// error:		err

func ConnectToServer(endpoint string) (net.Conn, error)

Writing a RPC session server ¶

You need to consider the followings when you implement a LRPC session server that serves all the RPC messages to an endpoint.

1. The process model. This depends on the nature of the messages/services. For most cases, it can be done simply by having a goroutine to serve all the messages for a LRPC connection. However, for NSS-related messages in Linux, it may be better to use a pre-configured pool of goroutines to serve all the requests as this will throttle such requests. This may or may not be necessary. Need to analyze performance test results first.

2. Message handling. For Windows, we may not need to protect the messages from snooping, and there may not be any need to implement sequence numbering and signing of request/request. However, we need to do this in *nix for security reasons.

This package currently provide a function that creates a RPC session server:

NewLrpc2SessionServer - creates a session server that uses a goroutine to serve all the messages for each LRPC connection.

Messages ¶

A message can be identified by message ID. You can choose any message number that you like for your messages. The only limitations are:

1. The mesasge ID MUST be unique for each endpoint.

2. Message ID must convert correctly into an uint16 value.

You need to register all the messages for an endpoint before you invoke the Start() method.

Message handler ¶

You need to implement a handler for each message as type CommandHandler. See description on type CommandHandler for details.

Writing application that needs LRPC service ¶

1. Create a client connection by calling NewLrpc2ClientSession().

2. Connect to the client using Connect()

3. Set up the arguments for the LRPC call as an array of interface{}.

4. Call lrpc.DoRequest() (if a response is expected) or lrpc.DoAsyncRequest() (if no response is expected).

5. When lrpc.DoRequest() is called, the results are passed back as an array of interface{}. Process the results.

Steps in writing a session server for a specific endpoint ¶

1. Call NewLrpc2SessionServer() (or provide your own function to create a session handler that implements the SessionServer interface).

2. Register the messages for the handler by calling one or more of the followings on the created message handler: RegisterMsgsByID() RegisterMsgByID()

3. Call the Start() method of the handler to start the service.

4. Call the Stop() method of the handler to stop the service.

5. Call the Wait() method of the handler to wait for the service to be completely shutdown.

6. Implement a handler function for each message.

7. If you need to save information for use for other messages sharing the same lrpc session, you can use the functions Get() and Set() in the associated SessionCtxt interface.