SEOSROUTE_VerifyCreate Function

SDK Guide › Authorization and Authentication API › SEOSROUTE_VerifyCreate Function

SEOSROUTE_VerifyCreate Function

The SEOSROUTE_VerifyCreate function performs a pseudo‑login to CA ControlMinder and returns the ACEE handle that is created.

The first six parameters must be supplied by the application; the last three 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 unsigned integer that is one of the following values:

SEOSAPI_AUTH_OK: The user is allowed to access the resource as requested.
SEOSAPI_AUTH_BADPASSWD_ERR: The password does not match the expected password.
SEOSAPI_AUTH_DENY: The request was denied.
SEOSAPI_AUTH_NORESPONSE_ERR: Seosd 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_NOUSERID_ERR: A user name was not supplied.
SEOSAPI_AUTH_NULLACEE_ERR: The phACEE parameter is a null pointer.
SEOSAPI_AUTH_REMOTE_ERR: The CA ControlMinder daemon returned an error described in szMsg.

Notes:

The SEOSROUTE_VerifyCreate function should be used only by a multi‑user (server ) process that performs services on behalf of other users. A single‑user process can call the SEOSROUTE_RequestAuth function without first calling the SEOSROUTE_VerifyCreate function.

To execute the SEOSROUTE_VerifyCreate function, the calling process must have an effective user ID of 0 or the user associated with the calling process must have the SERVER attribute.

int SEOSROUTE_VerifyCreate(const char   *szUserId,

                           const char   *szPwd,
                           const char   *szNewPwd,
                           int          bPwdChk,
                           const char   *szTerm,
                           int          LogOpt,
                           int          *phACEE,
                           API_AUTH_RES *pRes,
                           char         *szMsg);

szUserId

The name of the user for whom the ACEE is created. This parameter must be supplied.

szPwd

The password of the user identified by szUserId. If a NULL pointer is specified, CA ControlMinder skips the password check.

szNewPwd

The new password, should your application be changing the user's password in the CA ControlMinder database. Specify a NULL pointer if you are not specifying a new password or if a NULL pointer is specified for szPwd.

bPwdChk

A flag that determines whether the password is to be checked or not. You can combine the following flag values (using bitwise OR):

VERCRE_CHECK_CUR: Check that the current password is valid.
VERCRE_CHECK_NEW: In UNIX, check that the new password is valid according to active password policy rules.
VERCRE_CHECK_QUICKLOGIN: Simulate login without checking for time restrictions.

szTerm

The name of the terminal from which the user logged onto the system.

LogOpt

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

SEOSAPI_AUTH_LOGNONE: For server applications, 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 server applications, always create an audit record regardless of the database rules (value = 2).
SEOSAPI_AUTH_LOGFAIL: For server applications, create an audit record only if the authorization request fails and the database rules require it (value = 3).

phACEE

The ACEE handle returned by CA ControlMinder. This value is used by CA ControlMinder in subsequent authorization checks for the currently verified user.

pRes

A pointer to the API_AUTH_RES structure containing the authorization result.

szMsg

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

More information:

SEOSROUTE_VerifyDelete Function

API_AUTH_RES Structure

SEOSROUTE_VerifyDelete Function

The SEOSROUTE_VerifyDelete function releases an ACEE. Use this function to release ACEEs created using the SEOSROUTE_VerifyCreate function. Your application should release ACEEs once they are no longer required, because each allocated handle uses system resources and CA ControlMinder internal resources. These resources are limited.

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

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

SEOSAPI_AUTH_OK: The ACEE was released.
SEOSAPI_AUTH_NOACEE_ERR: The ACEE handle was not found.
SEOSAPI_AUTH_NORESPONSE_ERR: Seosd 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_NULLACEE_ERR: The phACEE parameter is a NULL pointer.
SEOSAPI_AUTH_REMOTE_ERR: The CA ControlMinder daemon returned an error described in szMsg.

Note: To execute the SEOSROUTE_VerifyDelete function, the calling process must have an effective user ID of 0 or the user associated with the calling process must have the SERVER attribute.

int SEOSROUTE_VerifyDelete(int  *phACEE,
                           int  bLog,

                           char *szMsg)

phACEE: A pointer to the handle of the ACEE to be released.
bLog: A flag that determines whether an audit log entry is created. It can have a value of 0 or 1. To create a log entry, set the bLog parameter to 1.
szMsg: A pointer to a buffer SEOSAPI_AUTH_MSGLEN bytes long into which CA ControlMinder returns a status message.

More information:

SEOSROUTE_VerifyCreate Function

Structures and Data Types

This section describes the data structures used by the Authorization and Authentication API functions to pass information back and forth between the functions and the CA ControlMinder daemons (in UNIX) and services (in Windows). Every field of each data structure is described.

The Authorization and Authentication API functions use the following structures:

API_AUTH_RES: Holds the result of an authorization check.
SEOS_ACCESS: Encapsulates a single member of type SEOS_ACCS.
SEOS_ACCS: Holds a list of access flags.
SEOS_OID: Holds an object identification descriptor.

API_AUTH_RES Structure

The API_AUTH_RES structure holds the results of an authorization check.

int result

A code indicating the result of the authorization check. Valid values are:

P-Requested access to resource was granted.
D-Requested access to resource was denied.
C-The access request check was incomplete.

int last_stage

The authorization stage at which the information in the structure was written. This information is useful if access was granted but the authorization failed later for some reason.

int grant_stage

The authorization stage at which the permit or deny decision was made.

SEOS_ACCS accs

An unsigned long integer representing the type of access requested.

SEOS_OID oidRes

The object ID of the resource for which authorization was checked.

SEOS_OID oidGroup

If accumulated group rights are being checked and if access is allowed or denied by a group, this member stores the object ID of the last group checked.

If accumulated group rights are not being checked and if access is allowed or denied by a group, this member stores the object ID of the group.

More information:

SEOS_ACCS Structure

API_AZN_RES Structure

The API_AZN_RES structure holds the results of an authorization check.

int result

A code indicating the result of the authorization check. Valid values are:

P-Permission to access the resource was granted.
D-The requested access was denied.
C-The database has been corrupted.

int last_stage

The authorization stage at which the information in the structure was written. This information is useful if access was granted but the authorization failed later for some reason.

int grant_stage

The authorization stage at which the permit or deny decision was made.

SEOS_ACCS accs

An unsigned long integer representing the type of access requested.

SEOS_OID oidRes

The object ID of the resource for which authorization was checked.

SEOS_OID oidGroup

If accumulated group rights are being checked and if access is allowed or denied by a group, this member stores the object ID of the last group checked.

If accumulated group rights are not being checked and if access is allowed or denied by a group, this member stores the object ID of the group.

SEOSDB_CDF dfRespTab

Structure representing the class definition of a record in the database.

SEOSDB_PDF pdfRespTab

Structure representing the property definition of a record in the database.

SEOSDB_ODF odfRespTab

Structure representing the object definition of a record in the database.

More information:

SEOS_ACCS Structure

SEOS_ACCESS Structure

The SEOS_ACCESS structure encapsulates a single member of the type SEOS_ACCS.

SEOS_ACCS accs: An unsigned long integer representing the type of access requested. A list of possible values is detailed for the SEOS_ACCS structure.

SEOS_ACCS Structure

The SEOS_ACCS data type is an unsigned long integer representing the type of access requested.

Access types currently defined for the APIs include the following:

For All Requests

SEOS_ACCS_ANY: Everything is allowed.
SEOS_ACCS_AUTHORIZE: Changing ACLs is allowed.
SEOS_ACCS_CREATE: Creating new files in class FILE and new objects in class ADMIN is allowed.
SEOS_ACCS_DELETE: Deleting is allowed (same as SEOS_ACCS_ERASE).
SEOS_ACCS_ERASE: Deleting is allowed.
SEOS_ACCS_EXEC: Executing programs is allowed.
SEOS_ACCS_FILESCAN: Scanning files is allowed.
SEOS_ACCS_JOIN: Adding users to groups or removing users from groups is allowed.
SEOS_ACCS_MODIFY: Renaming is allowed.
SEOS_ACCS_NONE: Nothing is allowed.
SEOS_ACCS_PASSWD: Changing password attributes is allowed.
SEOS_ACCS_READ: Read access is allowed.
SEOS_ACCS_RENAME: Renaming files is allowed.
SEOS_ACCS_WRITE: Write access is allowed.
SEOS_ACCS_reserved: Not used.

For UNIX Requests Only

SEOS_ACCS_CHOWN: Changing ownership is allowed.
SEOS_ACCS_CHGRP: Changing group setting is allowed.
SEOS_ACCS_CHMOD: Changing file mode is allowed.
SEOS_ACCS_UTIMES: Changing modification time of files is allowed.

Generic Attributes

SEOS_ACCS_SEC: Changing ACLs of files is allowed.

Macros for Multiple Access Requests

SEOS_ACCS_CHOG: CHOWN + CHGRP
SEOS_ACCS_UPDATE: READ + WRITE + EXEC
SEOS_ACCS_CONTROL: CHOG + CHMOD + UTIMES + SEC + UPDATE

Note: For possible additional values for this field, see the file ACDir/include/seostype.h.

SEOS_OID Data Type

The SEOS_OID data type is an unsigned long integer representing the object ID of a record in the database.

Each object in the database has a unique object ID. If you know the object ID, you can use seadmapi to retrieve information about the object.