The sec_login_newgroups( ) routine enables a principal to assume the minimum groupset that is required to accomplish a given task. For example, a user may have privilege attributes that include membership in an administrative group associated with a comprehensive permission set, and membership in a user group associated with a more restricted permission set. Such a user may not want the permissions associated with the administrative group, except when those permissions are essential to an administrative task (so as to avoid inadvertent damage to objects that are accessible to members of the administrative group, but not to members of the user group).
To offer users the capability of removing groups from their groupsets, an application may use the login API as shown in the following example.
Note: Two of the function calls that appear in the following example, sec_login_get_current_context( ) and sec_login_inquire_net_info( ), are described in the following topic.
sec_login_get_current_context(&login_context,&st);
sec_login_inquire_net_info(login_context,&net_info,&st);
for (i=0; i < num_groups; i++)
{
... query whether user wants to discard any current group
memberships. Copy new group set to new_groups array ...
}
if (!sec_login_newgroups(login_context,sec_login_no_flags,
num_new_groups, new_groups, &restricted_context,&st))
{
if (st == sec_login_s_groupset_invalid)
printf("Newgroupsetinvalid\n");
...application-specific error handling...
}
Note that the sec_login_newgroups( ) call can only return a restricted groupset: it cannot return a groupset larger than the one associated with the login context that is passed to it. This routine also enables the calling process to flag the new login context as private to the calling process.