Previous Topic: Authorization and Authentication APINext Topic: Access Authorization


Programming Guide

CA ControlMinder governs the user's access to a resource. Each resource belongs to a class that identifies the type of the resource. For example, records or objects of the TERMINAL class govern the user's ability to log in from a terminal. A user can access a specific resource only if the user has the permissions required to access the resource in the requested manner. For example, a user can log in from a terminal only if a rule (record) assigning the user read access to the terminal exists in the CA ControlMinder database. Note that the rule does not have to be an explicit assignment-you can also assign the authority using group membership or default access settings.

The CA ControlMinder function calls within the Authorization and Authentication API communicate with seosd on the local station. CA ControlMinder supports the following types of processes:

To use CA ControlMinder to protect the resources of an application, do this:

  1. Add a resource class to the database. Use this resource class to protect the objects of your application.

    Note: For more information about adding a new resource class to CA ControlMinder, see the seclassadm utility in the UNIX Utilities Guide.

  2. Add records to the application's class in the database. These records define rules for protecting your application's objects.
  3. Place CA ControlMinder Authorization and Authentication API calls in your program.
  4. Link the program with the CA ControlMinder library.

Both server and ordinary applications use the same library.

To use any of the CA ControlMinder functions, you must include the following line in your C code:

#include <api_auth.h>

The names of all the functions in the Authorization and Authentication API take the form SEOSROUTE_functionName.

This section includes sample code that demonstrates how to use some of the Authorization and Authentication API functions. Additional examples are provided in the following directories on your system drive:

Note: For more information about CA ControlMinder classes and objects, and about adding user‑defined resources, see the Reference Guide.

Checking the Access Authority for a User Process

Any application can use the CA ControlMinder Authorization and Authentication API to check whether the user can access a resource. You decide whether to perform resource access checks in your application. To write an application that uses the CA ControlMinder authorization mechanism, all you have to do is call a single API function called SEOSROUTE_RequestAuth with the appropriate parameters and check the return values.

The following program demonstrates how to check whether a user can access a resource:

UNIX Example

To test if CA ControlMinder allows you to surrogate to root by using the su root command, type the following command:

>upexamp SURROGATE USER.root
#include <stdio.h>
#include <string.h>
#include <memory.h>

#include “api_auth.h”

int ShowUsage(void)
{
     fprintf( stderr, “Usage:\n”
                    “ upexamp ClassName ResourceName\n”);
  return 1;
}

int main(int argc, char *argv[])
{ int               rv;
     char           buff[SEOSAPI_AUTH_MSGLEN];
     SEOS_ACCESS access;
     API_AUTH_RES result;     /* The result of request structure */
     if (argc != 3)
        return ShowUsage();
     memset(&access, 0, sizeof(access) );
     access.accs = SEOS_ACCS_READ;
     rv = SEOSROUTE_RequestAuth( argv[1],     /* Class Name        */
                                 argv[2],     /* Resource Name     */
                               SEOSAPI_AUTH_CURRACEE,      /*Myself*/
                               &access,
                               SEOSAPI_AUTH_LOGNONE,
                               &result,
                               buff);

     printf( “Result %s (0x%X)\n”, buff, rv );
     return 0;
}

After compiling and linking this example, you can check whether you have authorization to access a specific resource.

Windows Example

To test if CA ControlMinder lets you access a file that you were explicitly denied access to, type the following commands:

newfile D:\Winnt\system32\notepad.exe defaccess(all)
authorize file D:\Winnt\system32\notepad.exe \
          uid(your_UID) access(none)

>upexamp FILE D:\Winnt\system32\notepad.exe

The following sections describe the files used by the program.

In UNIX

The program uses the following files:

In Windows

If you installed CA ControlMinder on your system, the program uses the following files:

Application Servers

The Authorization and Authentication API includes an interface for application servers. The server application is assumed to provide service to many users. Only server applications can perform authorization checks on behalf of users, including the user associated with the process.

The server application must perform a “pseudo‑login” for each new connected client. Perform the pseudo‑login by calling the SEOSROUTE_VerifyCreate function. The SEOSROUTE_VerifyCreate function provides the application with an Accessor's Entry Element (ACEE) handle for the client.

From now on, the ACEE handle returned by the SEOSROUTE_VerifyCreate function makes each call to the CA ControlMinder authorization check module for the client. The application should carefully maintain these handles.

The application must perform a “pseudo‑logout” to release ACEE handles when a client disconnects from it or when it finishes providing service to the client. To perform the pseudo‑logout, call the SEOSROUTE_VerifyDelete function. If handles are not released, both system resources and CA ControlMinder internal resources remain allocated to the ACEE handle. If these resources remain allocated, the unnecessary allocations can cause the system to slow down and may result in the inability to log into the system.

Only processes running under effective UID 0 (root) or users with the SERVER attribute may issue SEOSROUTE_VerifyCreate, SEOSROUTE_VerifyDelete, and SEOSROUTE_RequestAuth calls with a handle other than SEOSAPI_AUTH_CURRACEE.

Example

The following program demonstrates how to use CA ControlMinder to manage the security aspects of a multi‑user process:

#include <stdio.h>
#include <string.h>
#include <memory.h>

#include “api_auth.h”

int ShowUsage(void)
{
     fprintf( stderr, “Usage:\n”
                        “ musexamp ClassName ResourceName
                           UserName\n”);
     return 1;
}

int main(int argc, char *argv[])
{ int          rv;
     int        usr_acee;
     char       msg_buff[SEOSAPI_AUTH_MSGLEN];
     SEOS_ACCESS   access;
     API_AUTH_RES                 result;
     /* The result of request structure */

     if (argc != 4)
        return ShowUsage();

     memset(&access, 0, sizeof(access) );
     access.accs = SEOS_ACCS_READ | SEOS_ACCS_WRITE | SEOS_ACCS_EXEC;

     rv = SEOSROUTE_VerifyCreate( argv[3], NULL, NULL, 0, NULL,
                                SEOSAPI_AUTH_LOG, &usr_acee,
                                &result, msg_buff );

     if (rv)
          { printf( “Return Value: 0x%08x\n”
               “Msg: '%s'\n”, rv, msg_buff );
                return 1;
                }
     else
          printf( “Got ACEE handle for user '%s': %d\n”, argv[3],
                    usr_acee );

     rv = SEOSROUTE_RequestAuth(argv[1],    /* Class Name         */
                         argv[2],           /* Resource Name      */
                         usr_acee,          /* User's ACEE Handle */
                         &access,
                         0,
                         &result,
                         msg_buff);

     if (rv)
          printf( “Return Value: 0x%08x\n”
               “Msg: '%s'\n”, rv, msg_buff );
     else    
          printf( “Pass !!!!\n” );

     rv = SEOSROUTE_VerifyDelete( &usr_acee, 1, msg_buff );

     if (rv)
          { printf( “Return Value: 0x%08x\n”
               “Msg: '%s'\n”, rv, msg_buff );
          return 1;
       }
     else
     printf(“Released ACEE handle for user '%s': %d\n”,
               argv[3], usr_acee );

     return 0;
}
In UNIX

The program uses the following files:

In Windows

Assuming that you installed CA ControlMinder on your system, the program uses the following files: