Previous Topic: Remote Authorization APINext Topic: SEOSROUTE_VerifyCreate Function


Files

The remote authorization API uses the following files:

Example

The following program demonstrates how a client application can perform a remote authorization check:

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

#include “api_auth.h”
#include “langapi.h”

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

int main(int argc, char *argv[])
{
char *output;
int rv;
API_AUTH_RES result;
char input[200];
char *Passwd = NULL;

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

    Passwd = getpass(“Please enter your password:”);
    if ( Passwd == NULL )
    {
       printf(“Illegal password!!\n”);
       return 1;
}

    /*
     * Initialization. get the host name and password from the
     * command line parameters
     */
    rv = lca_rmtauth_Init(“rmt_auth”, &output, argv[5], Passwd);
    if ( rv )
    {
        printf( “Return value: 0x%08x\n”
              “%s\n”, rv, (output) ? output : “Initialization failed” );
        return 1;
    }
    Passwd = NULL;

    /*
     * Send the request to the server and get the result
     */
rv = lca_rmtauth_CheckAccess(argv[1], argv[2], argv[3], argv[4], &result);
    if ( rv )
    {
        printf(“Return value: 0x%08x\n”
               “Remote Access Check failed\n”, rv);
        return 1;
    }

    /*
     * Print the results.
     * Further analysis as for the reasons for granting/denying
     * access can be made at this stage
     */
    printf(“%s's access %s to %s %s at %s is %s!!\n”,
               argv[1], argv[4], argv[2], argv[3], argv[5],
            ((char) result.result == 'P') ? “Permitted” : “Denied”);

    lca_Terminate();
}

After compiling and linking this example, you can check whether a user is authorized to access a specific resource. For example, to see whether user Joe has read access to file /etc/passwd, type the following command:

rmt_auth Joe FILE /etc/passwd Read authorizationservername

You are prompted for your password, after which you receive the reply.

More information:

Remote Authorization Operations

Functions

The Authorization and Authentication API consists of the following functions:

SEOSROUTE_ParseApiError

Converts an error string into the integer representing the error code.

SEOSROUTE_RequestAuth

Checks whether a user is authorized to access a resource using the specified access type.

SEOSROUTE_VerifyCreate

Creates an ACEE handle for a user.

SEOSROUTE_VerifyDelete

Deletes a user's ACEE handle.

SEOSROUTE_ParseApiError Function

The SEOSROUTE_ParseApiError function parses the error string returned by the verification and authentication functions and returns the integer value associated with it.

Notes:

szErrMsg

The error string returned by CA ControlMinder in the *szMsg parameter

SEOSROUTE_RequestAuth Function

The SEOSROUTE_RequestAuth function asks seosd whether the specified user is allowed to access the specified resource using the specified access type.

The SEOSROUTE_RequestAuth function sends the request to seosd, which first checks whether the parameters are valid. If they are, seosd performs its standard resource authorization check: Is the specified user authorized to access the specified resource in the specified way?

The first five parameters must be supplied by the application; the last two parameters are returned by CA ControlMinder and can be used by the application to make decisions and provide the user with status information.

The function returns an integer that takes on one of the following values:

SEOSAPI_AUTH_OK

The user is allowed to access the resource as requested.

SEOSAPI_AUTH_BADACCESS_ERR

An invalid access authority was specified.

SEOSAPI_AUTH_DENY

The request was denied.

SEOSAPI_AUTH_NORESPONSE_ERR

The seosd daemon is not responding.

SEOSAPI_AUTH_NOTROOT_ERR

The user ID of the calling process is not 0 (root), and the user executing the calling process does not have the SERVER attribute.

SEOSAPI_AUTH_REMOTE_ERR

The daemon or service returned an error described in szMsg.

Notes:

A server application normally calls SEOSROUTE_VerifyCreate before calling SEOSROUTE_RequestAuth, to get an ACEE handle for the user whose authorization is being checked.

szClass

The name of the class to which the resource belongs.

szEntity

The name of the record, or object, representing the resource being accessed.

Note: The case of the szEntity parameter is important when the szClass supports case-sensitive objects.

hACEE

The ACEE handle of the accessor. To specify the ACEE of the user associated with current process, specify SEOSAPI_AUTH_CURRACEE. Specifying an ACEE handle other than SEOSAPI_AUTH_CURRACEE requires the user associated with the calling process to have the SERVER attribute or the calling process to be running under the effective user ID of 0 (root).

pAccess

A pointer to a structure containing the requested access. The structure contains the single data member access of type SEOS_ACCS. Valid values for this member are:

LogOpt

A flag that determines whether an audit log entry must be made. Valid values are:

SEOSAPI_AUTH_LOGNONE

For regular users, which are not root, if the authorization request succeeds, do not create an audit record. If the authorization request fails, create an audit record if the current rules in the database require auditing.

For server applications and for root users, do not create an audit record, regardless of whether the authorization request succeeds or fails (value = 0).

SEOSAPI_AUTH_LOG

If the current rules in the database require it, create an audit record (value = 1).

SEOSAPI_AUTH_LOGALL

For regular users, this is an invalid option and is mapped to SEOSAPI_AUTH_LOG.

For server applications, always create an audit record regardless of the database rules (value = 2).

SEOSAPI_AUTH_LOGFAIL

For regular users, this is an invalid option and is mapped to SEOSAPI_AUTH_LOG.

For server applications, create an audit record only if the authorization request fails and the database rules require it (value = 3).

SEOSAPI_AUTH_LOGNONE_USER

For regular users (including root), if the authorization request succeeds, do not create an audit record. If the authorization request fails, create an audit record if the current rules in the database require auditing.

For server applications, do not create an audit record, regardless of whether the authorization request succeeds or fails (value = 4).

SEOSAPI_AUTH_LOGNEVER

Do not create an audit record (value = 5).

pRes

A pointer to the API_AUTH_RES structure containing the authorization result.

szMsg

A pointer to a buffer SEOSAPI_AUTH_MSGLEN into which CA ControlMinder returns a status message.

More information:

SEOSROUTE_VerifyCreate Function

API_AUTH_RES Structure

SEOSROUTE_RequestAuthAzn Function

The SEOSROUTE_RequestAuthAzn function sends seosd an authorization request. CA ControlMinder first checks whether the parameters are valid. If they are, CA ControlMinder performs its standard resource authorization check realized in function SEOSROUTE_RequestAuth.

Important! This function is obsolete and is available for backward compatibility purposes only.

If the function succeeds, the return value is zero. Otherwise, the return value is an error code.

int SEOSROUTE_RequestAzn (
     LPCSTR szClass,
     LPCSTR szEntity,
     LPCSTR szAccess,
     HANDLE *phUserAttributes,
     int hACEE,
     int LogOpt,
     API_AZN_RES  *pres,
     API_RESP_TAB **response,
     LPCSTR szMsg
);
hACEE

The ACEE handle of the accessor.

LogOpt

A flag that determines whether an audit log entry must be made.

phUserAttributes

A pointer to a hash table created by the function SEOSROUTE_Create RequestAzn. This pointer is related only to the SEOSD process.

pRes

A pointer to the API_AZN_RES structure containing the authorization result.

response

A pointer to the buffer containing the response list.

SzAccess

A pointer to a null terminated string that specifies the access name corresponding to the object described by szEntity.

SzClass

A pointer to a null terminated string containing the name of the resource class.

SzEntity

A pointer to a null terminated string containing the name of the object representing the resource being accessed.

Note: The case of the szEntity parameter is important when the szClass supports case-sensitive objects.

szMsg

A pointer to a buffer SEOSAPI_AUTH_MSGLEN bytes long into which CA ControlMinder returns a status message.

More information:

SEOSROUTE_RequestAuth Function

API_AZN_RES Structure

API_AZN_USERATTR Structure

SEOSROUTE_CloseRequestAzn Function

SEOSROUTE_CreateRequestAzn Function

The SEOSROUTE_CreateRequestAzn function sends seosd an array of the user attributes relating to same user and receives pointers specifying a hash table created on the user attributes base.

Note: It is important to call the SEOSROUTE_CloseRequestAzn function after processing a user.

If the function succeeds, the return value is zero. Otherwise, the return value is an error code.

INT SEOSROUTE_CreateRequestAzn(
     LPCSTR szUserDir,
     DWORD cEntries,
     LPAPI_AZN_USERATTR pUserAttr,
     PHANDLE phUserAttributes,
     LPSTR szMsg
);
SzUserDir in

Pointer to a null terminated string specifying the user directory.

CEntries

Value specifying the number of the API_AZN_USERATTR structures in array pointed to by pUserAttr. Cannot be zero (0).

PUserAttr in

Pointer to an array containing user attributes.

PhUserAttributes out

If the function succeeds, the parameter specifies a pointer to a hash table calculated using user attributes.

If the function fails, the value is INVALID_HANDLE_VALUE.

SzMsg out

A pointer to a buffer SEOSAPI_AUTH_MSGLEN bytes long into which CA ControlMinder returns a status message.

More information:

API_AZN_USERATTR Structure

SEOSROUTE_CloseRequestAzn Function

SEOSROUTE_RequestAuthAzn Function

SEOSROUTE_CloseRequestAzn Function

The SEOSROUTE_CloseRequestAzn function removes the hash table pointer by hUserAttributes. After calling this function, SEOSD cannot process authorization requests for the specified user unless SEOSROUTE_CreateRequestAzn( ) is processed again.

If the function succeeds, the return value is zero. Otherwise, the return value is an error code.

INT SEOSROUTE_CloseRequestAzn(
     HANDLE hUserAttributes,
     LPSTR szMsg
);
HUserAttributes in

A pointer to a hash table calculated using user attributes.

SzMsg out

A pointer to a buffer SEOSAPI_AUTH_MSGLEN bytes long into which CA ControlMinder returns a status message.

More information:

API_AZN_USERATTR Structure

SEOSROUTE_CreateRequestAzn Function

SEOSROUTE_RequestAuthAzn Function

API_AZN_USERATTR Structure

The API_AZN_USERATTR structure specifies attribute information.

typedef  struct tagAPI_AZN_USERATTR {
     char szAttName[ONAME_SIZE];
     char szAttVal[ONAME_SIZE];
}API_AZN_USERATTR, *PAPI_AZN_USERATTR, FAR *LPAPI_AZN_USERATTR;
szAttName

Null terminated string containing the attribute name.

szAttVal

Null terminated string containing the attribute value.

More information:

SEOSROUTE_CloseRequestAzn Function

SEOSROUTE_RequestAuthAzn Function