RPC Security: How to Register an RPC

Security for RPCs is handled through the RPC registration process. Each client application must create a context for itself, which checks if the application user has access to a "B"-type option in the Kernel menu system. Only RPCs assigned to that option can be run by the client application.

To enable your application to create a context for itself:

Create a "B"-type option in the OPTION file (#19) for your application.
The OPTION TYPE "B" represents a Broker client/server type option.

In the RPC multiple for this option type, add an entry for each RPC that your application calls. The following fields can be set up for each RPC in your option:

Field Name	Entry	Description
RPC (#.01)	Required	This field is used to enter a pointer to the REMOTE PROCEDURE file (#8994). This field links the remote procedure call in the REMOTE PROCEDURE file (#8994) to the package option.
RPCKEY (#1)	Optional	This field is used to restrict the use of a remote procedure call to a particular package option. The RPCKEY field is a free-text pointer to the SECURITY KEY file (#19.1).
RULES (#2)	Optional	This field is used to enter M code that is executed when an RPC request is made to verify whether the request should be honored.

When you export your package using KIDS, export both your RPCs and your package option. KIDS will automatically associate the RPCs with the package option.
Your application must create a context for itself on the server, which checks access to RPCs. In the initial code of your client application, make a call to the CreateContext method of your TRPCBroker component. Pass your application's "B"-type option's name as a parameter. For example:
```
if not RPCBroker1.CreateContext(option_name) then
  Application.Terminate;
```
If the CreateContext method returns True, only those RPCs designated in the RPC multiple of your application option will be permitted to run.

If the CreateContext method returns False, you should terminate your application (if you don't your application will run, but you will get errors every time you try to access an RPC).
End-users of your application must have the "B"-type option assigned to them on one of their menus, in order for CreateContext to return True. This allows system managers to control access to client applications.

Bypassing RPC Security for Development

Having the XUPROGMODE security key allows you to bypass the Broker security checks. You can run any RPC without regard to application context (without having to use the CreateContext method). This is a convenience for when you are developing an application. When you complete development, make sure you test your application from an account without the XUPROGMODE key, to ensure that all RPCs needed are properly registered.