1 – rdacl_get_access
NAME
rdacl_get_access - Reads a privilege attribute certificate
SYNOPSIS
#include <dce/rdaclif.h>
void rdacl_get_access(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_acl_permset_t *net_rights,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the object whose ACL is to be accessed.
component_name
A character string containing the name of the target object.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
Output
net_rights
The output list of access rights, in sec_acl_permset_t form.
This is a 32-bit set of permission flags supported by the
manager type.
status A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The rdacl_get_access() routine determines the complete extent of access
to the specified object by the calling process. Although the
rdacl_test_access() routines are the preferred method of testing access,
this routine is useful for implementing operations like the conventional
UNIX access function.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In order
to write an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the server
side of this interface. Test server code is included as a sample
implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
sec_acl_invalid_manager_type
The manager type is not valid.
sec_acl_invalid_acl_type
The ACL type is not valid.
sec_acl_not_authorized
The requested operation is not allowed.
sec_acl_object_not_found
The requested object could not be found.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
rdacl_test_access
2 – rdacl_get_manager_types
NAME
rdacl_get_manager_types - Lists the types of ACLs protecting an object
SYNOPSIS
#include <dce/rdaclif.h>
void rdacl_get_manager_types(
handle_t h,
sec_acl_component_name_t component_name,
sec_acl_type_t sec_acl_type,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_types,
uuid_t manager_types[],
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object.
component_name
A character string containing the name of the target object.
sec_acl_type
The ACL type. The sec_acl_type_t data type distinguishes the
various types of ACLs an object can possess for a given manager
type. The possible values are as follows:
+ sec_acl_type_object
+ sec_acl_type_default_object
+ sec_acl_type_default_container
size_avail
An unsigned 32-bit integer containing the allocated length of the
manager_types[] array.
Output
size_used
An unsigned 32-bit integer containing the number of output
entries returned in the manager_types[] array.
num_types
An unsigned 32-bit integer containing the number of types
returned in the manager_types[] array. This is always equal
to size_used.
manager_types[]
An array of length size_avail to contain UUIDs (of type uuid_t)
identifying the different types of ACL managers protecting the
target object.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The rdacl_get_manager_types() routine returns a list of the types of
ACLs protecting an object. For example, in addition to the regular file
system ACL, a file representing the stable storage of some database
could have an ACL manager that supported permissions allowing database
updates only on certain days of the week.
ACL editors and browsers can use this operation to determine the ACL
manager types that a particular reference monitor is using to protect a
selected entity. Then, using the rdacl_get_printstring() routine, they
can determine how to format for display the permissions supported by a
specific manager.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In order
to write an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the server
side of this interface. Test server code is included as a sample
implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
rdacl_get_printstring
3 – rdacl_get_mgr_types_semantics
NAME
rdacl_get_manager_types_semantics - Lists the ACL manager types
protecting an object and the
POSIX semantics supported by
each manager type
SYNOPSIS
#include <dce/rdaclif.h>
void rdacl_get_mgr_types_semantics(
handle_t h,
sec_acl_component_name_t component_name,
sec_acl_type_t sec_acl_type,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_types,
uuid_t manager_types[],
sec_acl_posix_semantics_t posix_semantics[],
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object.
component_name
A character string containing the name of the target object.
sec_acl_type
The ACL type used to limit the function's output to ACL managers
that control the specified types of ACLs. The possible values
are as follows:
+ sec_acl_type_object - Object ACL, the ACL controlling access
to an object.
+ sec_acl_type_default_object - Initial Object ACL, the default
ACL for objects created in a container object.
+ sec_acl_type_default_container - Initial Container ACL, the
default ACL for containers created in a container object.
size_avail
An unsigned 32-bit integer containing the allocated length of the
manager_types[] and the posix_semantics[] arrays.
Output
size_used
An unsigned 32-bit integer containing the number of output
entries returned in the manager_types[] array.
num_types
An unsigned 32-bit integer containing the number of types
returned in the manager_types[] array. This is always equal
to size_used.
manager_types[]
An array of length size_avail containing the returned UUIDs (of
type uuid_t) identifying the different ACL manager types
protecting the target object.
posix_semantics[]
An array of length size_avail containing the POSIX semantics (of
type sec_acl_posix_semantics_t) that are supported by each
returned ACL manager type.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The rdacl_get_manager_types_semantics() routine returns a list of the
ACL manager types protecting an object and a list of the POSIX semantics
supported by those ACL manager types. Access to an object can be
controlled by multiple ACL manager types. For example, access to a file
representing the stable storage of a database could be controlled by two
ACL manager types each with completely different sets of permissions:
one to provide standard file system access (read, write, execute, etc.)
and one to provide access that allows database updates only on certain
days of the week.
ACL editors and browsers can use this operation to determine the ACL
manager types that a particular reference monitor is using to protect a
selected entity. Then, using the rdacl_get_printstring() routine, they
can determine how to format for display the permissions supported by a
specific manager.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In order
to write an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the server
side of this interface. Test server code is included as a sample
implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
rdacl_get_printstring
4 – rdacl_get_printstring
NAME
rdacl_get_printstring - Returns printable ACL strings
SYNOPSIS
#include <dce/rdaclif.h>
void rdacl_get_printstring(
handle_t h,
uuid_t *manager_type,
unsigned32 size_avail,
uuid_t *manager_type_chain,
sec_acl_printstring_t *manager_info,
boolean32 *tokenize,
unsigned32 *total_num_printstrings,
unsigned32 *size_used,
sec_acl_printstring_t printstrings[],
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
rdacl_get_manager_types() to acquire a list of the manager
types protecting a given object.
size_avail
An unsigned 32-bit integer containing the allocated length of the
printstrings[] array.
Output
manager_type_chain
If the target object ACL contains more than 32 permission bits,
multiple manager types are used, one for each 32-bit wide "slice"
of permissions. The UUID returned in manager_type_chain refers
to the next ACL manager in the chain. If there are no more ACL
managers for this ACL, uuid_nil is returned.
manager_info
Provides a name and helpstring for the given ACL manager.
tokenize
When FALSE this variable indicates that the returned permission
printstrings are unambiguous and therefore may be concatenated
when printed without confusion. When TRUE, however, this property
does not hold, and the strings need to be separated when printed
or passed.
total_num_printstrings
An unsigned 32-bit integer containing the total number of
permission printstrings supported by this ACL manager type.
size_used
An unsigned 32-bit integer containing the number of permission
entries returned in the printstrings[] array.
printstrings[]
An array of permission printstrings of type sec_acl_printstring_t.
Each entry of the array is a structure containing three
components:
printstring
A character string of maximum length sec_acl_printstring_len
containing the printable representation of a specified
permission.
helpstring
A character string of maximum length
sec_acl_printstring_help_len containing some text that can
be used to describe the specified permission.
permissions
A sec_acl_permset_t permission set describing the
permissions that are to be represented with the companion
printstring. The array consists of one such entry for
each permission supported by the ACL manager identified
by manager_type.
status
A pointer to the completion status. On successful completion, the
routine returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The rdacl_get_printstring() routine returns an array of printable
representations (called printstrings) for each permission bit or
combination of permission bits the specified ACL manager will support.
The ACL manager type specified must be one of the types indicated by
the ACL handle.
In addition to returning the printstrings, this routine also returns
instructions about how to print the strings. When the tokenize variable
is set to FALSE, a print string might be r or w, which could be
concatenated in the display as rw without any confusion. However, when
the tokenize variable is TRUE, it implies the printstrings might be of
a form like read or write, which must be displayed separated by spaces
or colons or something.
In any list of permission printstrings, there may appear to be some
redundancy. ACL managers often define aliases for common permission
combinations. By convention, however, simple entries need to appear
at the beginning of the printstrings[] array, and combinations need to
appear at the end.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In
order to write an ACL manager, a programmer must implement the entire
rdacl interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the
server side of this interface. Test server code is included as a
sample implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not among those referenced by
the input handle.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
rdacl_get_manager_types
5 – rdacl_get_referral
NAME
rdacl_get_referral - Gets a referral to an ACL update site
SYNOPSIS
#include <dce/rdaclif.h>
void rdacl_get_referral(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_acl_type_t sec_acl_type,
sec_acl_tower_set_t *towers[],
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object.
component_name
A character string containing the name of the target object.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
sec_acl_type
The ACL type. The sec_acl_type_t data type distinguishes the
various types of ACLs an object can possess for a given manager
type. The possible values are as follows:
+ sec_acl_type_object
+ sec_acl_type_default_object
+ sec_acl_type_default_container
Output
towers[]
A pointer to address information indicating an ACL update site.
This information, obtained from the RPC runtime, is used by the
client-side code to construct a new ACL binding handle indicating
a site that will not return the sec_acl_site_readonly error.
The sec_acl_tower_set_t structure contains an array of towers
(called towers[]) and an unsigned 32-bit integer indicating the
number of array elements (called count). This type enables the
client to pass in an unallocated array of towers and have the
server allocate the correct amount.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The rdacl_get_referral() routine obtains a referral to an ACL update
site. This function is used when the current ACL site yields a
sec_acl_site_readonly error. Some replication managers will require all
updates for a given object to be directed to a given replica. If
clients of the generic ACL interface know they are dealing with an
object that is replicated in this way, this function allows them to
recover from the problem and rebind to the proper update site. The DCE
network registry, for example, is replicated this way.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In
order to write an ACL manager, a programmer must implement the entire
rdacl interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the server
side of this interface. Test server code is included as a sample
implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
6 – rdacl_lookup
NAME
rdacl_lookup - Returns the ACL for an object
SYNOPSIS
#include <dce/rdaclif.h>
void rdacl_lookup(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_acl_type_t sec_acl_type,
sec_acl_result_t *result);
PARAMETERS
Input
h A handle referring to the target object.
component_name
A character string containing the name of the target object.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
sec_acl_type
The ACL type. The sec_acl_type_t data type distinguishes the
various types of ACLs an object can possess for a given
manager type. The possible values are as follows:
+ sec_acl_type_object
+ sec_acl_type_default_object
+ sec_acl_type_default_container
Output
result A pointer to a tagged union of type sec_acl_result_t. The tag
is the completion status, result.st. If result.st is equal to
error_status_ok, the union contains an ACL. Otherwise, the
completion status indicates an error, and the union is empty.
If the call returned successfully, the
result.tagged_union.sec_acl_list_t structure contains a
sec_acl_list_t. This data type is an array of pointers to
sec_acl_ts that define ACLs. If the permission set of the
returned ACL is 32 bits or smaller, sec_acl_list_t points to
only one sec_acl_t. If the permission set of the returned ACL
is larger than 32 bits, multiple sec_acl_ts are used to hold
them, and the sec_acl_list_t points to multiple sec_acl_ts.
DESCRIPTION
The rdacl_lookup() routine loads into memory a copy of an object's ACL
corresponding to the specified manager type. The routine returns a
pointer to the ACL. This routine is only used by ACL editors and
browsers; an application would use sec_acl_test_access() or
sec_acl_test_access_on_behalf() to process the contents of an ACL.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In order
to write an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the server
side of this interface. Test server code is included as a sample
implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
sec_acl_cant_allocate_memory
The requested operation requires more memory than is avail-
able.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_test_access
sec_acl_test_access_on_behalf
7 – rdacl_replace
NAME
rdacl_replace - Replaces an ACL
SYNOPSIS
#include <dce/rdaclif.h>
void rdacl_replace(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_acl_type_t sec_acl_type,
sec_acl_list_t *sec_acl_list,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object.
component_name
A character string containing the name of the target object.
manager_type
A pointer to the UUID identifying the type of the ACL manager in
question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
sec_acl_type
The ACL type. The sec_acl_type_t data type distinguishes the
various types of ACLs an object can possess for a given manager
type. The possible values are as follows:
+ sec_acl_type_object
+ sec_acl_type_default_object
+ sec_acl_type_default_container
sec_acl_list
The new ACL to use for the target object. This is represented by
a pointer to the sec_acl_list_t structure containing the complete
Access Control List. An ACL contains a list of ACL entries, the
UUID of the default cell where authentication takes place
(foreign entries in the ACL contain the name of their parent
cell), and the UUID of the ACL manager to interpret the list.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The rdacl_replace() routine replaces the ACL indicated by the input
handle with the information in the sec_acl_list parameter. ACLs are
thought of as immutable, and in order to modify them, an editing
application must read an entire ACL (using the sec_acl_lookup()
routine), modify it as needed, and replace it using this routine.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In
order to write an ACL manager, a programmer must implement the entire
rdacl interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the server
side of this interface. Test server code is included as a sample
implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_lookup
8 – rdacl_test_access
NAME
rdacl_test_access - Tests access to an object
SYNOPSIS
#include <dce/rdaclif.h>
boolean32 rdacl_test_access(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_acl_permset_t desired_permset,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object.
component_name
A character string containing the name of the target object.
manager_type
A pointer to the UUID identifying the type of the ACL manager in
question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
desired_permset
A permission set in sec_acl_permset_t form containing the desired
privileges. This is a 32-bit set of permission flags supported by
the manager type.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The rdacl_test_access() routine determines if the specified ACL contains
entries granting privileges to the calling process matching those in
desired_permset. An application generally only inquires after the
minimum set of privileges needed to accomplish a specific task.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In
order to write an ACL manager, a programmer must implement the entire
rdacl interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the server
side of this interface. Test server code is included as a sample
implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
rdacl_test_access_on_behalf
9 – rdacl_test_access_on_behalf
NAME
rdacl_test_access_on_behalf - Tests access to an object on behalf of
another process
SYNOPSIS
#include <dce/rdaclif.h>
boolean rdacl_test_access_on_behalf(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_id_pac_t *subject,
sec_acl_permset_t desired_permset,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object.
component_name
A character string containing the name of the target object.
manager_type
A pointer to the UUID identifying the type of the ACL manager in
question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
subject
A Privilege Attribute Certificate (PAC) for the subject process.
The PAC contains the name and UUID of the principal and parent
cell of the subject process, as well as a list of any groups to
which it belongs. The PAC also contains a flag (named
authenticated). When set, it indicates that the certificate was
obtained from an authenticated source. When not set, the
certificate must not be trusted. (The field is FALSE when it was
obtained from the rpc_auth layer and the protect level was set to
rpc_c_protect_level_none. This indicates that no authentication
protocol was actually used in the remote procedure call; the
identity was simply transmitted from the caller to the callee.
If an authentication protocol was used, then the flag is set to
TRUE.) A server uses rpc_binding_inq_auth_client() to acquire a
certificate for the client process.
desired_permset
A permission set in sec_acl_permset_t form containing the desired
privileges. This is a 32-bit set of permission flags supported
by the manager type.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The rdacl_test_access_on_behalf() routine determines if the specified
ACL contains entries granting privileges to the subject, a process
besides the calling process, matching those in desired_permset. This
routine succeeds only if the access is available to both the caller
process as well as the subject identified in the call. An application
will generally only inquire after the minimum set of privileges needed
to accomplish a specific task.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In order
to write an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the server
side of this interface. Test server code is included as a sample
implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
rdacl_test_access
rpc_binding_inq_auth_client
10 – sec_acl_bind
NAME
sec_acl_bind - Returns a handle for an object's ACL
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_bind(
unsigned char *entry_name,
boolean32 bind_to_entry,
sec_acl_handle_t *h,
error_status_t *status);
PARAMETERS
Input
entry_name
The name of the target object. Subsequent ACL operations using the
returned handle will affect the ACL of this object.
bind_to_entry
Bind indicator, for use when entry_name identifies both an entry
in the global namespace and an actual object. A TRUE value binds
the handle to the entry in the namespace, while FALSE binds the
handle to the actual object.
Output
h A pointer to the sec_acl_handle_t variable to receive the returned
ACL handle. The other sec_acl routines use this handle to refer
to the ACL for the object specified with entry_name.
status
A pointer to the completion status. On successful completion, the
routine returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_acl_bind() routine returns a handle bound to the indicated
object's ACL. This routine is central to all the other sec_acl
routines, each of which requires this handle to identify the ACL on
which to operate.
NOTES
If the specified name is both an actual object, and an entry in the
global namespace, there are two ACLs associated with it. For example,
in addition to the ACL normally attached to file system objects, the
root directory of a file system has an ACL corresponding to its entry
in the global namespace. This controls access by outsiders to the entire
file system, whereas the resident ACL for the root directory only
controls access to the directory and, by inheritance, its sub-
directories. The ambiguity must be resolved with the bind_to_entry
parameter.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
sec_acl_object_not_found
The requested object could not be found.
sec_acl_no_acl_found
There is no ACL associated with the specified object.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
11 – sec_acl_bind_to_addr
NAME
sec_acl_bind_to_addr - Returns a handle to an object identified by
its network address
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_bind_to_addr(
unsigned char *site_addr,
sec_acl_component_name_t component_name,
sec_acl_handle_t *h,
error_status_t *status);
PARAMETERS
Input
site_addr
An RPC string binding to the fully qualified network address of
the target object.
component_name
The name of the target object. Subsequent ACL operations using
the returned handle will affect the ACL of this object.
Output
h A pointer to the sec_acl_handle_t variable to receive the
returned ACL handle. The other sec_acl routines use this
handle to refer to the ACL for the object specified with
entry_name.
status A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_acl_bind_to_addr() routine returns a handle bound to the
indicated object's ACL manager. This routine and the sec_acl_bind()
routine are central to all the other sec_acl routines, each of which
requires a handle to identify the ACL on which to operate.
This routine differs from sec_acl_bind() in that it binds to the network
address of the target object, rather than to a cell namespace entry.
Therefore, unlike sec_acl_bind(), it is possible to pass
sec_acl_bind_to_addr() a null string as a component name and to bind
with a nonexistent name. The purpose of this call is to eliminate the
necessity of looking up an object's name. To validate the name, use
sec_acl_bind().
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
sec_acl_object_not_found
The requested object could not be found.
sec_acl_no_acl_found
There is no ACL associated with the specified object.
sec_acl_unable_to_authenticate
The call could not authenticate to the server that manages
the target object's ACL.
sec_acl_bind_error
The call could not bind to the requested site.
sec_acl_invalid_site_name
The site_addr parameter is invalid.
sec_acl_cant_allocate_memory
Memory allocation failure.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
12 – sec_acl_calc_mask
NAME
sec_acl_calc_mask - Returns the sec_acl_type_mask_obj entry for the
specified ACL list
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_calc_mask(
sec_acl_list_t *sec_acl_list,
error_status_t *status);
PARAMETERS
Input/Output
*sec_acl_list
A pointer to a sec_acl_type_t the specifies the number of ACLs of
each ACL type. The sec_acl_type_t data type distinguishes between
the various types of ACLs an object can possess for a given
manager. In the file system, for example, most objects have only
one ACL, controlling the access to that object, but objects that
control the creation of other objects (sometimes referred to as
"containers") may have more. A directory, for example, can have
ACLs to be used as initial values when member objects are created.
Do not confuse ACL types with the permissions corresponding to
different ACL manager types or with the ACL manager types them-
selves.
Output
status
A pointer to the completion status. On successful completion, the
routine returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_acl_calc_mask() routine calculates and sets the
sec_acl_e_type_mask_obj entry of the specified ACL list. The value of
the sec_acl_e_type_mask_obj entry is the union of the permissions of all
ACL entries that refer to members of the File Group Class.
This operation is performed locally, within the client. The function
does not check to determine if the manager to which the specified ACL
list will be submitted supports the sec_acl_e_type_mask_obj entry type.
The calling application must determine whether to call this routine,
after obtaining the required, if any, POSIX semantics, via the
sec_acl_get_mgr_types_semantics() routine.
NOTES
This call is provided in source code form.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
sec_acl_cant_allocate_memory
Requested operation requires more memory than is available.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
13 – sec_acl_get_access
NAME
sec_acl_get_access - Lists the access (permission set) that the caller
has for an object
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_get_access(
sec_acl_handle_t h,
uuid_t *manager_type,
sec_acl_permset_t *net_rights,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the object whose ACL is to be accessed.
Use sec_acl_bind() to create this handle.
manager_type
A pointer to the UUID identifying the manager type of the ACL in
question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
Output
net_rights
The output list of access rights in sec_acl_permset_t form.
This is a 32-bit set of permission flags supported by the
manager type.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_acl_get_access() routine determines the complete extent of
access to the specified object by the calling process. Although the
sec_acl_test_access() and sec_acl_test_access_on_behalf() routines are
the preferred method of testing access, this routine is useful for
implementing operations like the conventional UNIX access function.
Permissions Required
The sec_acl_get_access() routine requires at least one permission of any
kind on the object for which the access is to be returned.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_acl_test_access
sec_acl_test_access_on_behalf
14 – sec_acl_get_error_info
NAME
sec_acl_get_error_info - Returns error information from an ACL handle
SYNOPSIS
#include <dce/daclif.h>
error_status_t sec_acl_get_error_info(
sec_acl_handle_t h);
PARAMETERS
Input
h A handle referring to the target ACL. The handle is bound to the
ACL with the sec_acl_bind() routine, which also specifies the
name of the object to which the target ACL belongs.
DESCRIPTION
The sec_acl_get_error_info() routine returns error information from the
specified ACL handle.
During a call to a routine in the sec_acl Application Programming
Interface (API), error codes received from the RPC runtime or other
APIs are saved in the ACL handle and a corresponding error code from
the sec_acl set is passed back by the ACL API. The
sec_acl_get_error_info() routine returns the last error code stored
in the ACL handle for those clients who need to know exactly what went
wrong.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
RETURN VALUES
This routine returns a value of type error_status_t, indicating the
cause of the last error issued by the RPC runtime.
ERRORS
sec_acl_invalid_handle
The ACL handle specified by sec_acl_handle_t is invalid.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_lookup
15 – sec_acl_get_manager_types
NAME
sec_acl_get_manager_types - Lists the manager types of the ACLs
protecting an object
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_get_manager_types(
sec_acl_handle_t h,
sec_acl_type_t sec_acl_type,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_types,
uuid_t manager_types[],
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object. Use sec_acl_bind() to
create this handle.
sec_acl_type
The ACL type. The sec_acl_type_t data type distinguishes the
various types of ACLs an object can possess for a given manager
type. The possible values are as follows:
+ sec_acl_type_object
+ sec_acl_type_default_object
+ sec_acl_type_default_container
size_avail
An unsigned 32-bit integer containing the allocated length of the
manager_types[] array.
Output
size_used
An unsigned 32-bit integer containing the number of output
entries returned in the manager_types[] array.
num_types
An unsigned 32-bit integer containing the number of types
returned in the manager_types[] array. This may be greater
than size_used if there was not enough space allocated in the
manager_types[] array for all the manager types.
manager_types[]
An array of length size_avail to contain UUIDs (of type uuid_t)
identifying the different types of ACL managers protecting the
target object.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_acl_get_manager_types() routine returns a list of the manager
types of ACLs of type sec_acl_type that are protecting the object
identified by h. For example, in addition to the regular file system
ACL, a file representing the stable storage of some database could have
an ACL manager that supported permissions allowing database updates
only on certain days of the week.
ACL editors and browsers can use this operation to determine the ACL
manager types that a particular reference monitor is using to protect a
selected entity. Then, using the sec_acl_get_printstring() routine, they
can determine how to format for display the permissions supported by a
specific manager.
Permissions Required
The sec_acl_get_manager_types() routine requires at least one permission
of any kind on the object for which the ACL manager types are to be
returned.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_get_printstring
16 – sec_acl_get_manager_types_semantics
NAME
sec_acl_get_mgr_types_semantics - Lists the manager types of the ACLs
protecting an object
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_get_mgr_types_semantics(
sec_acl_handle_t h,
sec_acl_type_t sec_acl_type,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_types,
uuid_t manager_types[],
sec_acl_posix_semantics_t posix_semantics[],
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object. Use sec_acl_bind() to
create this handle.
sec_acl_type
The ACL type. The sec_acl_type_t data type distinguishes the
various types of ACLs an object can possess for a given manager
type. The possible values are as follows:
+ sec_acl_type_object
+ sec_acl_type_default_object
+ sec_acl_type_default_container
size_avail
An unsigned 32-bit integer containing the allocated length of
the manager_types[] array.
Output
size_used
An unsigned 32-bit integer containing the number of output
entries returned in the manager_types[] array.
num_types
An unsigned 32-bit integer containing the number of types
returned in the manager_types[] array. This may be greater
than size_used if there was not enough space allocated in the
manager_types[] array for all the manager types.
manager_types[]
An array of length size_avail to contain UUIDs (of type uuid_t)
identifying the different types of ACL managers protecting the
target object.
posix_semantics[]
An array of POSIX semantics supported by each manager type with
entries of type sec_acl_posix_semantics_t.
status A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_acl_get_mgr_types_semantics() routine returns a list of the
manager types of ACLs of type sec_acl_type that are protecting the
object identified by h. For example, in addition to the regular file
system ACL, a file representing the stable storage of some database
could have an ACL manager that supported permissions allowing database
updates only on certain days of the week.
ACL editors and browsers can use this operation to determine the ACL
manager types that a particular reference monitor is using to protect a
selected entity. Then, using the sec_acl_get_printstring() routine, they
can determine how to format for display the permissions supported by a
specific manager.
Permissions Required
The sec_acl_get_mgr_types_semantics() routine requires at least one
permission of any kind on the object for which the ACL manager types
are to be returned.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_get_printstring
17 – sec_acl_get_printstring
NAME
sec_acl_get_printstring - Returns printable ACL strings
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_get_printstring(
sec_acl_handle_t h,
uuid_t *manager_type,
unsigned32 size_avail,
uuid_t *manager_type_chain,
sec_acl_printstring_t *manager_info,
boolean32 *tokenize,
unsigned32 *total_num_printstrings,
unsigned32 *size_used,
sec_acl_printstring_t printstrings[],
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object. Use sec_acl_bind() to
create this handle.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
size_avail
An unsigned 32-bit integer containing the allocated length of the
printstrings[] array.
Output
manager_type_chain
If the target object ACL contains more than 32 permission bits,
multiple manager types are used, one for each 32-bit wide
"slice" of permissions. The UUID returned in manager_type_chain
refers to the next ACL manager in the chain. If there are no
more ACL managers for this ACL, uuid_nil is returned.
manager_info
Provides a name and helpstring for the given ACL manager.
tokenize
When FALSE, this variable indicates that the returned permission
printstrings are unambiguous and therefore may be concatenated
when printed without confusion. When TRUE, however, this
property does not hold, and the strings need to be separated
when printed or passed.
total_num_printstrings
An unsigned 32-bit integer containing the total number of
permission printstrings supported by this ACL manager type.
size_used
An unsigned 32-bit integer containing the number of permission
entries returned in the printstrings[] array.
printstrings[]
An array of permission printstrings of type
sec_acl_printstring_t. Each entry of the array is a
structure containing the following three components:
printstring
A character string of maximum length
sec_acl_printstring_len describing the printable
representation of a specified permission.
helpstring
A character string of maximum length
sec_acl_printstring_help_len containing some text that
can be used to describe the specified permission.
permissions
A sec_acl_permset_t permission set describing the
permissions that are represented with the companion
printstring. The array consists of one such entry
for each permission supported by the ACL manager
identified by manager_type.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_acl_get_printstring() routine returns an array of printable
representations (called "printstrings") for each permission bit or
combination of permission bits the specified ACL manager supports.
The ACL manager type specified must be one of the types protecting
the object indicated by h.
In addition to returning the printstrings, this routine also returns
instructions about how to print the strings. When the tokenize variable
is set to FALSE, a printstring might be r or w, which could be
concatenated in the display as rw without any confusion. However, when
the tokenize variable is TRUE, it implies the printstrings might be of
a form like read or write, which must be displayed separated by spaces
or colons or something.
In any list of permission printstrings, there may appear to be some
redundancy. ACL managers often define aliases for common permission
combinations. By convention, however, simple entries should appear
at the beginning of the printstrings[] array, and combinations should
appear at the end.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not among those referenced
by the input handle.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_get_manager_types
18 – sec_acl_lookup
NAME
sec_acl_lookup - Returns the ACL for an object
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_lookup(
sec_acl_handle_t h,
uuid_t *manager_type,
sec_acl_type_t sec_acl_type,
sec_acl_list_t *sec_acl_list,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object. Use sec_acl_bind() to
create this handle.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
sec_acl_type
The ACL type. The sec_acl_type_t data type distinguishes the
various types of ACLs an object can possess for a given manager
type. The possible values are as follows:
+ sec_acl_type_object
+ sec_acl_type_default_object
+ sec_acl_type_default_container
Output
sec_acl_list
A pointer to the sec_acl_list_t structure to receive the complete
Access Control List. An ACL contains a list of ACL entries, the
UUID of the default cell where authentication takes place
(foreign entries in the ACL contain the name of their home cell),
and the UUID of the ACL manager to interpret the list.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_acl_lookup() routine loads into memory a copy of an object's
ACL corresponding to the specified manager type. The routine returns
a pointer to the ACL. This routine is only used by ACL editors and
browsers; an application would use sec_acl_test_access() or
sec_acl_test_access_on_behalf() to process the contents of an ACL.
Permissions Required
The sec_acl_lookup() routine requires at least one permission of any
kind on the object for which the ACL is to be returned.
NOTES
The memory containing the sec_acl_t structure for each ACL is
dynamically allocated. Use the sec_acl_release() routine to return
each ACL's memory block to the pool when an application is finished
with the ACLs.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
sec_acl_cant_allocate_memory
The requested operation requires more memory than is avail-
able.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_test_access
sec_acl_test_access_on_behalf
19 – sec_acl_release
NAME
sec_acl_release - Releases ACL storage
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_release(
sec_acl_handle_t h,
sec_acl_t *sec_acl,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object. Use sec_acl_bind() to
create this handle.
sec_acl
A pointer to the complete ACL associated with the target object.
Output
status
A pointer to the completion status. On successful completion, the
routine returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_acl_release() routine releases any local storage associated with
the ACL object, returning it to the pool. This is strictly a local
operation (since the storage in question is local), and has no effect on
the remote object or its ACL. The ACL handle is in the argument list
only for consistency with other sec_acl routines.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_lookup
20 – sec_acl_release_handle
NAME
sec_acl_release_handle - Removes an ACL handle
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_release_handle(
sec_acl_handle_t *h,
error_status_t *status);
PARAMETERS
Input
h The handle to be removed. The handle is bound to the object to
which the ACL belongs with the sec_acl_bind() routine.
Output
status
A pointer to the completion status. On successful completion, the
routine returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_acl_release_handle() routine removes the specified handle.
This is strictly a local operation, and has no effect on the remote
object or its ACL.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
21 – sec_acl_replace
NAME
sec_acl_replace - Replaces an ACL
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_replace(
sec_acl_handle_t h,
uuid_t *manager_type,
sec_acl_type_t sec_acl_type,
sec_acl_list_t *sec_acl_list,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object. Use sec_acl_bind() to
create this handle.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
sec_acl_type
The ACL type. The sec_acl_type_t data type distinguishes the
various types of ACLs an object can possess for a given manager
type. The possible values are as follows:
+ sec_acl_type_object
+ sec_acl_type_default_object
+ sec_acl_type_default_container
sec_acl_list
The new ACL to use for the target object. This is represented by a
pointer to the sec_acl_list_t structure containing the complete
Access Control List. An ACL contains a list of ACL entries, the
UUID of the default cell where authentication will take place
(foreign entries in the ACL contain the name of their parent
cell), and the UUID of the ACL manager to interpret the list.
Output
status
A pointer to the completion status. On successful completion, the
routine returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_acl_replace() routine replaces the ACL indicated by the input
handle with the information in the sec_acl_list parameter. ACLs are
thought of as immutable, and in order to modify them, an editing
application must read an entire ACL (using the sec_acl_lookup()
routine), modify it as needed, and replace it using this routine.
Permissions Required
The sec_acl_replace() routine requires the c (control) permission on the
object for which the ACL is to be replaced.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_lookup
22 – sec_acl_test_access
NAME
sec_acl_test_access - Tests access to an object
SYNOPSIS
#include <dce/daclif.h>
boolean32 sec_acl_test_access(
sec_acl_handle_t h,
uuid_t *manager_type,
sec_acl_permset_t desired_permset,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object. Use sec_acl_bind() to
create this handle.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
desired_permset
A permission set in sec_acl_permset_t form containing the desired
privileges. This is a 32-bit set of permission flags supported by
the manager type.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_acl_test_access() routine determines if the specified ACL
contains entries granting privileges to the calling process matching
those in desired_permset. An application generally only inquires after
the minimum set of privileges needed to accomplish a specific task.
Permissions Required
The sec_acl_test_access() routine requires at least one permission of
any kind on the object for which the privileges are to be tested.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
RETURN VALUES
The routine returns TRUE if the calling application program is
authorized to access the target object with the privileges in
desired_permset.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_test_access_on_behalf
23 – sec_acl_test_access_on_behalf
NAME
sec_acl_test_access_on_behalf - Tests access to an object on behalf of
another process
SYNOPSIS
#include <dce/daclif.h>
boolean32 sec_acl_test_access_on_behalf(
sec_acl_handle_t h,
uuid_t *manager_type,
sec_id_pac_t *subject,
sec_acl_permset_t desired_permset,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object. Use sec_acl_bind() to
create this handle.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
subject
A Privilege Attribute Certificate (PAC) for the subject process.
The PAC contains the name and UUID of the principal and cell of
the subject process, as well as a list of any groups to which it
belongs. The PAC also contains a flag (named authenticated).
When set, it indicates that the certificate was obtained from an
authenticated source. When not set, the certificate must not be
trusted. (The field is FALSE when it was obtained from the
rpc_auth layer and the protect level was set to
rpc_c_protect_level_none. This indicates that no authentication
protocol was actually used in the remote procedure call; the
identity was simply transmitted from the caller to the callee.
If an authentication protocol was used, then the flag is set to
TRUE.) If a null PAC is passed, the subject is treated as an
"anonymous user", matching only the any_other and unauthenticated
entries (if they exist) on the ACL. A server uses
rpc_binding_inq_auth_client() to acquire a certificate for the
client process.
desired_permset
A permission set in sec_acl_permset_t form containing the desired
privileges. This is a 32-bit set of permission flags supported by
the manager type.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_acl_test_access_on_behalf() routine determines if the specified
ACL contains entries that grant the privileges specified in
desired_permset to the subject process. An application generally
inquires about only the minimum set of privileges needed to accomplish
a specific task.
Permissions Required
The sec_acl_test_access_on_behalf() routine requires at least one
permission of any kind on the object for which the privileges are to
be tested. Both the calling process and the identified subject must
have permission on the object.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
RETURN VALUES
If the routine completes successfully (with a completion status of
error_status_ok) it returns a value of
+ TRUE if the caller has any access (at least one permission of any
kind), and the subject has the desired_permset privileges.
+ FALSE if both the caller and the subject have any access, but the
subject does not have the desired_permset privileges.
If the routine does not complete successfully, it returns a bad
completion status code and a return value of FALSE.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_test_access
rpc_binding_inq_auth_client
24 – sec_attr_trig_query
NAME
sec_attr_trig_query - Reads attributes coded with an attribute trigger
type of query
SYNOPSIS
#include <dce/sec_attr_trig.h>
void sec_attr_trig_query (
handle_t h,
sec_attr_component_name_t cell_name,
sec_attr_component_name_t component_name,
sec_attr_trig_cursor_t *cursor,
unsigned32 num_attr_keys,
unsigned32 space_avail,
sec_attr_t attr_keys[],
unsigned32 *num_returned,
sec_attr_t attrs[],
sec_attr_trig_timeval_sec_t time_to_live[],
unsigned32 *num_left,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the trigger server to be accessed Use the
trigger binding information specified in the attribute encoding
to acquire a bound handle.
cell_name
A value of sec_attr_component_name_t that identifies the cell in
which the object whose attribute is to be accessed resides.
Supply a NULL cell_name to specify the local cell (/.:).
component_name
A value of sec_attr_component_name_t that identifies the name of
the object whose attribute is to be accessed. If cell_name
specifies a foreign cell, component_name is interpreted as a
UUID in string format since the caller of this interface knows
only the UUID, not the name, of the foreign principal.
num_attr_keys
An unsigned 32-bit integer that specifies the number of elements
in the attr_keys[] array. This integer must be greater than 0.
space_avail
An unsigned 32-bit integer that specifies the size of the
attr_keys[] array.
attr_keys[]
An array of values of type sec_attr_t. For each attribute
instance, the sec_attr_t array contains an attr_id (a UUID of
type uuid_t) to identify the attribute to be queried and an
attr_value. attr_value can be used to pass in optional
information required by the attribute trigger query. If no
additional information is to be passed, set attr_value to
sec_attr_enc_void. This is actually accomplished by setting the
sec_attr_encoding_t data type to sec_attr_enc_void. The size
of the attr_keys[] array is determined by num_attr_keys.
Input/Output
cursor
A pointer to a cursor of type sec_attr_trig_cursor_t. As an input
parameter, cursor can be initialized (by the
sec_addr_trig_cursor_init routine) or uninitialized. As an output
parameter, cursor is positioned past the attributes returned in
this call.
Output
num_returned
A pointer to an unsigned 32-bit integer that specifies the number
of attribute instances returned in the attr_keys[] array.
attrs[]
An array of values of type sec_attr_t. The size of this array is
determined by the space_avail parameter and the length by the
num_returned parameter.
time_to_live[],
An array of values of type sec_attr_trig_timeval_sec_t. For
each attribute in the attrs[] array, The time_to_live[] array
specifies the time in seconds that the attribute can be safely
cached.
num_left
A pointer to an unsigned 32-bit integer that supplies the number
of attributes found but not returned because of space constraints
in the attrs[] buffer.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_attr_trig_query() routine reads attributes coded with an
attribute trigger type of query.
The sec_attr_trig_query() routine is called by the DCE attribute lookup
code for all schema entries that specify a query attribute trigger
(sec_attr_trig_type_query specified with the sec_attr_trig_type_flags_t
data type). The attribute query code passes the sec_attr_trig_query()
input parameters to a user-written query attribute trigger server and
receives the output parameters back from the server. Although generally
this routine it is not called directly, this reference page is provided
for users who are writing the attribute trigger servers that will
receive sec_attr_trig_query() input and supply its output.
Multi-valued attributes are returned as independent attribute instances
sharing the same attribute UUID. A read of an attribute set returns all
instances of members of the set; the attribute set instance is not
returned.
For objects in the local cell, set the cell_name parameter to null, and
the component_name parameter to specify the object's name.
For objects in a foreign cell, set the cell_name parameter to identify
the name of the foreign cell, and the component_name parameter to the
UUID in string format that identifies the object in the foreign cell.
The cursor parameter specifies a cursor of type sec_attr_trig_cursor_t
that establishes the point in the attribute list at which to start
processing the query. Use the sec_attr_trig_cursor_init function to
initialize a list cursor. If cursor is uninitialized, the server begins
processing the query at the first attribute that satisfies the search
criteria. Note that generally, sec_attr_trig_cursor_init function makes
a remote call to the specified server. To initialize the cursor without
making this remote call, set the sec_attr_trig_cursor_init function
valid parameter to 0.
The num_left parameter contains the number of attributes that were found
but could not be returned because of space constraints of the attrs[]
array. (Note that this number may be inaccurate if the target server
allows updates between successive queries.) To obtain all of the
remaining attributes, set the size of the attrs[] array so that it is
large enough to hold the number of attributes listed in num_left.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_ATTR_TRIG.IDL
The idl file from which sec_attr_trig.h was derived.
ERRORS
not_all_available
unauthorized
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_attr_trig_cursor_init
sec_attr_trig_update
25 – sec_attr_trig_update
NAME
sec_attr_trig_update - For attributes coded with an attribute trigger
type of update, passes attribute updates to an
update attribute trigger server for evaluation
SYNOPSIS
#include <dce/sec_attr_trig.h>
void sec_attr_trig_update (
handle_t h,
sec_attr_component_name_t cell_name,
sec_attr_component_name_t component_name,
unsigned32 num_to_write,
unsigned32 space_avail,
sec_attr_t in_attrs[],
unsigned32 *num_returned,
sec_attr_t out_attrs[],
unsigned32 *num_left,
signed32 *failure_index,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the trigger server to be accessed. Use the
trigger binding information specified in the attribute encoding
to acquire a bound handle.
cell_name
A value of sec_attr_component_name_t that identifies the cell
in which the object whose attribute is to be accessed resides.
Supply a NULL cell_name to specify the local cell (/.:).
component_name
A value of sec_attr_component_name_t that identifies the name of
the object whose attribute is to be accessed. If cell_name
specifies a foreign cell, component_name is interpreted as a
UUID in string format since the caller of this interface knows
only the UUID, not the name, of the foreign principal.
num_to_write
An unsigned 32-bit integer that specifies the number of elements
in the in_attrs array. This integer must be greater than 0.
space_avail
An unsigned 32-bit integer that specifies the size of the
out_attrs array.
in_attrs[]
An array of values of type sec_attr_t that specifies the
attribute instances to be written. The size of in_attrs[]
is determined by num_to_write.
Output
num_returned
A pointer to an unsigned 32-bit integer that specifies the number
of attribute instances returned in the out_attrs[] array.
out_attrs[]
An array of values of type sec_attr_t. These values, supplied by
the update attribute trigger server, are in a form suitable for
storage in the registry database.
num_left
A pointer to an unsigned 32-bit integer that supplies the number
of attributes that were found but not returned because of space
constraints in the out_attrs[] buffer.
failure_index
In the event of an error, failure_index is a pointer to the
element in the in_attrs[] array that caused the update to fail.
If the failure cannot be attributed to a specific attribute, the
value of failure_index is -1.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_attr_trig_update() routine passes attributes coded with an
attribute trigger type of update to a user-written update attribute
trigger server for evaluation before the updates are made to the
registry.
Although generally this routine it is not called directly, this
reference page is provided for users who are writing the attribute
trigger servers that will receive sec_attr_trig_update() input and
supply its output.
The sec_attr_trig_update() routine is called by the DCE attribute update
code for all schema entries that specify an update attribute trigger
(sec_attr_trig_type_update specified with the sec_attr_trig_type_flags_t
data type). The attribute update code passes the sec_attr_trig_update()
input parameters to a user-written update attribute trigger server and
receives the output parameters back from the server. The attribute
trigger server is responsible for evaluating the semantics of the entry
in order to reject or accept it, and the attribute trigger server may
even make changes in the output it sends back to the update code to
ensure the entry adheres to the semantics. The output received from
the attribute trigger server is in a form to be stored in the registry.
(Note that update attribute trigger servers do not store attribute
values. Attribute values are stored in the registry database.)
This is an atomic operation: if the update of any attribute in the
array fails to pass the evaluation, all updates are aborted. The
attribute causing the update to fail is identified in failure_index.
If the failure cannot be attributed to a given attribute, failure_index
contains -1.
For objects in the local cell, set the cell_name parameter to null, and
the component_name parameter to specify the object's name.
For objects in a foreign cell, set the cell_name parameter the the name
of the foreign cells, and the component_name parameter to specify the
UUID in string format that identifies the object in the foreign cell.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_ATTR_TRIG.IDL
The idl file from which dce/sec_attr_trig.h was derived.
ERRORS
database read only
server unavailable
invalid/unsupported attribute type
invalid encoding type
value not unique
site read only
unauthorized
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_attr_trig_query
26 – sec_cred_free_attr_cursor
NAME
sec_cred_free_attr_cursor - Free the local resources allocated to a
sec_attr_cursor_t used by the
sec_cred_get_extended_attrs() call
SYNOPSIS
#include <dce/sec_cred.h>
void sec_cred_free_attr_cursor (
sec_cred_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input/Output
cursor
As input, a pointer to a sec_cred_attr_cursor_t whose resources
are to be freed. As output a pointer to an initialized
sec_cred_attr_cursor_t with allocated resources freed.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_cred_free_attr_cursor() routine frees the resources assoicated
with a cursor of type sec_cred_attr_cursor_t used by the
sec_cred_get_extended_attrs() call.
ERRORS
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_extended_attrs
sec_cred_initialize_attr_cursor
27 – sec_cred_free_cursor
NAME
sec_cred_free_cursor - Release local resources allocated to a
sec_cred_cursor_t used by the
sec_cred_get_delegate() call
SYNOPSIS
#include <dce/sec_cred.h>
void sec_cred_free_cursor (
sec_cred_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input/Output
cursor
As input, a sec_cred_cursor_t whose resources are to be freed.
As output, a sec_cred_cursor_t whose resources are freed.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_cred_free_cursor() routine releases local resources allocated
to a sec_cred_cursor_t used by the sec_cred_get_delegate() call.
ERRORS
sec_login_s_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_initialize_cursor
28 – sec_cred_free_pa_handle
NAME
sec_cred_free_pa_handle - Free the local resources allocated to
a privilege attribute handle of type
sec_cred_pa_handle_t used by the
sec_cred_get_initiator() and
sec_cred_get_delegate() calls
SYNOPSIS
#include <dce/sec_cred.h>
void sec_cred_free_pa_handle (
sec_cred_pa_handle__t *pa_handle,
error_status_t *status);
PARAMETERS
Input/Output
pa_handle
As input, a pointer to a sec_cred_pa_handle_t whose resources
are to be freed. As output a pointer to a sec_cred_pa_handle_t
with allocated resources freed.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_cred_free_pa_handle() routine frees the resources assoicated
with a privilege attribute handle of type sec_cred_pa_handle_t used
by the sec_cred_get_initiator() and sec_cred_get_delegate() calls.
ERRORS
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_initiator
sec_cred_get_delegate
29 – sec_cred_get_authz_session_info
NAME
sec_cred_get_authz_session_info - Returns session-specific information
that represents an authenticated
client's credentials.
SYNOPSIS
#include <dce/sec_cred.h>
void sec_cred_get_authz_session_info(
rpc_authz_cred_handle_t callers_identity,
uuid_t *session_id,
sec_timeval_t *session_expiration,
error_status_t *status );
PARAMETERS
Input
callers_identity
A credential handle of type rpc_authz_cred_handle_t. This handle is
supplied as output of the rpc_binding_inq_auth_caller() call.
Output
session_ID
A pointer to a uuid_t that identifies the client's DCE authorization
session.
session_expiration
A pointer to a sec_timeval_t that specifies the expiration time of
the authenticated client's credentials.
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_cred_get_authz_session_info() routine retrieves session-specific
information that represents the credentials of authenticated client
specified by callers_identity. If the client is a member of a delegation
chain, the information represents the credentials of all members of the
chain.
The information can aid application servers in the construction of
identity-based caches. For example, it could be used as a key into a
cache of previously allocated delegation contexts and thus avoid the
overhead of allocating a new login context on every remote operation.
It could also be used as a key into a table of previously computed
authorization decisions.
Before you execute this call, you must execute an
rpc_binding_inq_auth_caller() call to obtain an rpc_authz_cred_handle_t
for the callers_identity parameter.
ERRORS
sec_cred_s_authz_cannot_comply
error_status_ok
RELATED INFORMATION
Functions: sec_intro
rpc_binding_inq_auth_caller
30 – sec_cred_get_client_princ_name
NAME
sec_cred_get_client_princ_name - Returns the principal name associated
with a credential handle
SYNOPSIS
#include <dce/sec_cred.h>
void sec_cred_get_client_princ_name(
rpc_authz_cred_handle_t callers_identity,
unsigned_char_p_t *client_princ_name,
error_status_t *status);
PARAMETERS
Input
callers_identity
A handle of type rpc_authz_cred_handle_t to the credentials for
which to return the principal name. This handle is supplied as
output of the rpc_binding_inq_auth_caller() call.
Output
client_princ_name
A pointer to the principal name of the server's rpc client.
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_cred_get_client_princ_name() routine extracts the principal name
associated with the credentials identified by callers_pas.
Before you execute sec_cred_get_client_princ_name(), you must execute an
rpc_binding_inq_auth_caller() call to obtain an rpc_authz_cred_handle_t
for the callers_identity parameter.
ERRORS
sec_cred_s_authz_cannot_comply
error_status_ok
RELATED INFORMATION
Functions: sec_intro
rpc_binding_inq_auth_caller
31 – sec_cred_get_deleg_restrictions
NAME
sec_cred_get_deleg_restrictions - Returns delegate restrictions
from a privilege attribute handle
SYNOPSIS
#include <dce/sec_cred.h>
sec_id_restriction_set_t *sec_cred_get_deleg_restrictions(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
PARAMETERS
Input
callers_pas
A value of type sec_cred_pa_handle_t that provides a handle to a
principal's privilege attributes. This handle is supplied as output
of the sec_cred_get_initiator() call, the sec_cred_get_delegate()
call and the sec_login_cred calls.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_deleg_restrictions () routine extracts delegate
restrictions from the privilege attribute handle identified by
callers_pas. The restrictions are returned in a
sec_id_restriction_set_t.
Before you execute sec_cred_get_pa_data(), you must execute a
sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
ERRORS
sec_cred_s_invalid_pa_handle
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_get_initiator
32 – sec_cred_get_delegate
NAME
sec_cred_get_delegate - Returns a handle to the privilege attributes
of an intermediary in a delegation chain
SYNOPSIS
#include <dce/sec_cred.h>
sec_cred_pa_handle_t sec_cred_get_delegate(
rpc_authz_cred_handle_t callers_identity,
sec_cred_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input
callers_identity
A handle of type rpc_authz_cred_handle_t. This handle is supplied
as output of the rpc_binding_inq_auth_caller() call.
Input/Output
cursor
As input, a pointer to a cursor of type sec_cred_cursor_t that has
been initialized by the sec_cred_initialize_cursor() call. As an
output parameter, cursor is a pointer to a cursor of type
sec_attr_srch_cursor_t that is positioned past the principal whose
privilege attributes have been returned in this call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_delegate() routine returns a handle to the the
privilege attributes of an intermediary in a delegation chain that
performed an authenticated RPC operation.
This call is used by servers. Clients use the
sec_login_cred_get_delegate() routine to return the privilege attribute
handle of an intermediary in a delegation chain.
The credential handle identified by callers_identity contains authenti-
cation and authorization information for all delegates in the chain.
This call returns a handle (sec_cred_pa_handle_t) to the privilege
attributes of one of the delegates in the binding handle. The
sec_cred_pa_handle_t returned by this call is used in other
sec_cred_get... calls to obtain privilege attribute information for a
single delegate.
To obtain the privilege attributes of each delegate in the credential
handle identified by callers_identity, execute this call until the
message sec_cred_s_no_more_entries is returned.
Before you execute sec_cred_get_delegate(), you must execute:
+ An rpc_binding_inq_auth_caller() call to obtain an
rpc_authz_cred_handle_t for the callers_identity parameter.
+ A sec_cred_initialize_cursor() call to initialize a cursor of type
sec_cred_cursor_t.
Use the sec_cred_free_pa_handle() all to free the resources associated
with the sec_cred_pa_handle_t.
ERRORS
sec_cred_s_invalid_auth_handle
sec_cred_s_invalid_cursor
sec_cred_s_no_more_entries
error_status_ok
RELATED INFORMATION
Functions: sec_intro
rpc_binding_inq_auth_caller
sec_cred_initialize_cursor
sec_cred_get_deleg_restrictions
sec_cred_get_delegation_type
sec_cred_get_extended_attrs
sec_cred_get_opt_restrictions
sec_cred_get_pa_date
sec_cred_get_req_restrictions
sec_cred_get_tgt_restrictions
sec_cred_get_v1_pac
sec_cred_free_pa_handle
33 – sec_cred_get_delegation_type
NAME
sec_cred_get_delegation_type - Returns the delegation type from a
privilege attribute handle
SYNOPSIS
#include <dce/sec_cred.h>
sec_id_delegation_type_t *sec_cred_get_delegation_type(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
PARAMETERS
Input
callers_pas
A value of type sec_cred_pa_handle_t that provides a handle to
a principal's privilege attributes. This handle is supplied as
output of either the sec_cred_get_initiator() call or
ec_cred_get_delegate() call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_delegation_type () routine extracts the delegation
type from the privilege attribute handle identified by callers_pas
and returns it in a sec_id_delegation_type_t.
Before you execute sec_cred_get_delegation_type(), you must execute a
sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
ERRORS
sec_cred_s_invalid_pa_handle
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_get_initiator
34 – sec_cred_get_extended_attrs
NAME
sec_cred_get_extended_attrs - Returns extended attributes from a
privilege handle
SYNOPSIS
#include <dce/sec_cred.h>
void sec_cred_get_extended_attrs(
sec_cred_pa_handle_t callers_pas,
sec_cred_attr_cursor_t *cursor
sec_attr_t *attr
error_status_t *status);
PARAMETERS
Input
callers_pas
A handle of type sec_cred_pa_handle_t to the caller's privilege
attributes. This handle is supplied as output of either the
sec_cred_get_initiator() call or sec_cred_get_delegate() call.
Input/Output
cursor
A cursor of type sec_cred_attr_cursor_t that has been initialized
by the sec_cred_initialize_attr_cursor() routine. As input cursor
must be initialized. As output, cursor is positioned at the first
attribute after the returned attribute.
Output
attr
A pointer to a value of sec_attr_t that contains extended registry
attributes.
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_extended_attrs() routine extracts extended registry
initialized from the privilege attribute handle identified by
callers_pas.
Before you execute call, you must execute:
+ A sec_cred_get_initiator() or sec_cred_get_delegate() call to
obtain a sec_cred_pa_handle_t for the callers_pas parameter.
+ A sec_cred_initialize_attr_cursor() to initialize a sec_attr_t.
To obtain all the extended registry attributes in the privilege
attribute handle, repeat sec_cred_get_extended_attrs() calls until
the status message no_more_entries_available is returned.
ERRORS
sec_cred_s_invalid_pa_handle
sec_cred_s_invalid_cursor
sec_cred_s_no_more_entries
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_initialize_attr_cursor
sec_cred_get_initiator
sec_cred_get_delegate
35 – sec_cred_get_initiator
NAME
sec_cred_get_initiator - Returns the privilege attributes of the
initiator of a delegation chain
SYNOPSIS
#include <dce/sec_cred.h>
sec_cred_pa_handle_t sec_cred_get_initiator(
rpc_authz_cred_handle_t callers_identity,
error_status_t *status);
PARAMETERS
Input
callers_identity
A credential handle of type rpc_authz_cred_handle_t. This handle
is supplied as output of the rpc_binding_inq_auth_caller() call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_initiator() routine returns a handle to the the
privilege attributes of the initiator of a delegation chain that
performed an authenticated RPC operation.
The credential handle identified by callers_identity contains
authentication and authorization information for all delegates in
the chain. This call returns a handle (sec_cred_pa_handle_t) to the
privilege attributes of the client that initiated the delegation chain.
The sec_cred_pa_handle_t returned by this call is used in other
sec_cred_get... calls to obtain privilege attribute information for the
initiator.
Before you execute sec_cred_get_initiator(), you must execute an
rpc_binding_inq_auth_caller() call to obtain an rpc_authz_cred_handle_t
for the callers_identity parameter.
ERRORS
sec_cred_s_invalid_auth_handle
error_status_ok
RELATED INFORMATION
Functions: sec_intro
rpc_binding_inq_auth_caller
sec_cred_get_deleg_restrictions
sec_cred_get_delegation_type
sec_cred_get_extended_attrs
sec_cred_get_opt_restrictions
sec_cred_get_pa_date
sec_cred_get_req_restrictions
sec_cred_get_tgt_restrictions
sec_cred_get_v1_pac
36 – sec_cred_get_opt_restrictions
NAME
sec_cred_get_opt_restrictions - Returns optional restrictions from
a privilege handle
SYNOPSIS
#include <dce/sec_cred.h>
sec_id_opt_req_t *sec_cred_get_opt_restrictions(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
PARAMETERS
Input
callers_pas
A handle of type sec_cred_pa_handle_t to a principal's privilege
attributes. This handle is supplied as output of either the
sec_cred_get_initiator() call or sec_cred_get_delegate() call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_opt_restrictions () routine extracts optional
restrictions from the privilege attribute handle identified by
callers_pas and returns them in a sec_id_restriction_set_t.
Before you execute sec_cred_get_pa_data(), you must execute a
sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
ERRORS
sec_cred_s_invalid_pa_handle
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_get_initiator
37 – sec_cred_get_pa_data
NAME
sec_cred_get_pa_data - Returns identity information from a privilege
attribute handle
SYNOPSIS
#include <dce/sec_cred.h>
sec_id_pa_t *sec_cred_get_pa_data(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
PARAMETERS
Input
callers_pas
A handle of type sec_cred_pa_handle_t to a principal's privilege
attributes. This handle is supplied as output of either the
sec_cred_get_initiator() call or sec_cred_get_delegate() call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_pa_data() routine extracts identity information from
the privilege attribute handle specified by callers_pas and returns it
in a sec_id_pa_t. The identity information includes an identifier of
the princpal's locall cell and the principal's local and foreign group
sets.
Before you execute sec_cred_get_pa_data(), you must execute a
sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
ERRORS
sec_cred_s_invalid_pa_handle
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_get_initiator
38 – sec_cred_get_req_restrictions
NAME
sec_cred_get_req_restrictions - Returns required restrictions
from a privilege attribute handle
SYNOPSIS
#include <dce/sec_cred.h>
sec_id_opt_req_t *sec_cred_get_req_restrictions (
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
PARAMETERS
Input
callers_pas
A handle of type sec_cred_pa_handle_t to a principal's privilege
attributes. This handle is supplied as output of either the
sec_cred_get_initiator() call or sec_cred_get_delegate() call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_req_restrictions() routine extracts required
restrictions from the privilege attribute handle identified by
callers_pas and returns them in a sec_id_opt_req_t.
Before you execute sec_cred_get_req_restrictions(), you must execute a
sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
ERRORS
sec_cred_s_invalid_pa_handle
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_get_initiator
39 – sec_cred_get_tgt_restrictions
NAME
sec_cred_get_tgt_restrictions - Returns target restrictions from a
privilege attribute handle
SYNOPSIS
#include <dce/sec_cred.h>
sec_id_restriction_set_t *sec_cred_get_tgt_restrictions(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
PARAMETERS
Input
callers_pas
A handle of type sec_cred_pa_handle_t to a principal's privilege
attributes. This handle is supplied as output of either the
sec_cred_get_initiator() call or sec_cred_get_delegate() call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_tgt_restrictions() routine extracts target
restrictions from the privilege attribute handle identified by
callers_pas and returns them in a sec_id_restriction_set_t.
Before you execute sec_cred_get_tgt_restrictions(), you must execute a
sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
ERRORS
sec_cred_s_invalid_pa_handle
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_get_initiator
40 – sec_cred_get_v1_pac
NAME
sec_cred_get_v1_pac - Returns pre-1.1 PAC from a privilege attribute
handle
SYNOPSIS
#include <dce/sec_cred.h>
sec_id_pac_t *sec_cred_get_v1_pac(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
PARAMETERS
Input
callers_pas
A handle of type sec_cred_pa_handle_t to the principal's privilege
attributes. This handle is supplied as output of either the
sec_cred_get_initiator() call or sec_cred_get_delegate() call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_v1_pac() routine extracts the privilege attributes
from a pre-1.1 PAC for the privilege attribute handle specified by
callers_pas and returns them in a sec_id_pa_t.
Before you execute sec_cred_get_v1_pac(), you must execute a
sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
ERRORS
sec_cred_s_invalid_pa_handle
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_get_initiator
41 – sec_cred_initialize_attr_cursor
NAME
sec_cred_initialize_attr_cursor - Initialize a sec_attr_cursor_t used
by the sec_cred_get_extended_attrs()
call
SYNOPSIS
#include <dce/sec_cred.h>
void sec_cred_initialize_attr_cursor (
sec_cred_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input/Output
cursor
As input, a pointer to a sec_cred_attr_cursor_t to be
initialized. As output a pointer to an initialized
sec_cred_attr_cursor_t.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_cred_initialize_attr_cursor() routine allocates and initializes
a cursor of type sec_cred_attr_cursor_t for use with the
sec_cred_get_extended_attrs() call. Use the sec_cred_free_attr_cursor()
call to free the resources allocated to cursor.
ERRORS
sec_login_s_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_extended_attrs
sec_cred_free_attr_cursor
42 – sec_cred_initialize_cursor
NAME
sec_cred_initialize_cursor - Initialize a sec_cred_cursor_t used by
the sec_cred_get_delegate() call
SYNOPSIS
#include <dce/sec_cred.h>
void sec_cred_initialize_cursor (
sec_cred_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input/Output
cursor
As input, a sec_cred_cursor_t to be initialized. As output,
an initialized sec_cred_cursor_t.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_cred_initialize_cursor() routine initializes a cursor of type
sec_cursor_t for use with the sec_cred_get_delegate() call. Use the
sec_cred_free_cursor() call to free the resources allocated to cursor.
ERRORS
sec_login_s_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_free_cursor
43 – sec_cred_is_authenticated
NAME
sec_cred_is_authenticated - Returns true if the supplied credentials
are authenticated and false if they are
not
SYNOPSIS
#include <dce/sec_cred.h>
boolean32 sec_cred_is_authenticated(
rpc_authz_cred_handle_t callers_identity,
error_status_t *status);
PARAMETERS
Input
callers_identity
A handle of type rpc_authz_cred_handle_t to the credentials to
check for authentication. This handle is supplied as output of
the rpc_binding_inq_auth_caller() call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_cred_is_authenticated() routine returns true if the credentials
identified by callers_identity are authenticated or false if they are
not.
Before you execute this call, you must execute an
rpc_binding_inq_auth_caller() call to obtain an rpc_authz_cred_handle_t
for the callers_identity parameter.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_CRED.IDL
The idl file from which dce/sec_cred.h was derived.
RETURN VALUES
The routine returns true is the credentials are authenticated; false if
they are not.
ERRORS
TBS
RELATED INFORMATION
Functions: sec_intro
rpc_binding_inq_auth_caller
44 – sec_id_gen_group
NAME
sec_id_gen_group - Generates a global name from cell and group UUIDs
SYNOPSIS
#include <dce/secidmap.h>
void sec_id_gen_group(
sec_rgy_handle_t context,
uuid_t *cell_idp,
uuid_t *group_idp,
sec_rgy_name_t global_name,
sec_rgy_name_t cell_namep,
sec_rgy_name_t group_namep,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
cell_idp
A pointer to the UUID of the home cell of the group whose name is
in question.
group_idp
A pointer to the UUID of the group whose name is in question.
Output
global_name
The global (full) name of the group in sec_rgy_name_t form.
cell_namep
The name of the group's home cell in sec_rgy_name_t form.
group_namep
The local (with respect to the home cell) name of the group in
sec_rgy_name_t form.
status
A pointer to the completion status. On successful completion, the
function returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_id_gen_group() routine generates a global name from input cell
and group UUIDs. For example, given a UUID specifying the
cell /.../world/hp/brazil, and a UUID specifying a group resident in
that cell named writers, the routine would return the global name of
that group, in this case, /.../world/hp/brazil/writers. It also returns
the simple names of the cell and group, translated from the UUIDs.
The routine will not produce translations to any name for which a NULL
pointer has been supplied.
FILES
SYS$COMMON:[DCE$LIBRARY]SECIDMAP.IDL
The idl file from which dce/secidmap.h was derived.
ERRORS
sec_id_e_name_too_long
The name is too long for current implementation.
sec_id_e_bad_cell_uuid
The cell UUID is not valid.
sec_rgy_object_not_found
The registry server could not find the specified group.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_id_gen_name
sec_id_parse_group
sec_id_parse_name
45 – sec_id_gen_name
NAME
sec_id_gen_name - Generates a global name from cell and principal
UUIDs
SYNOPSIS
#include <dce/secidmap.h>
void sec_id_gen_name(
sec_rgy_handle_t context,
uuid_t *cell_idp,
uuid_t *princ_idp,
sec_rgy_name_t global_name,
sec_rgy_name_t cell_namep,
sec_rgy_name_t princ_namep,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
cell_idp
A pointer to the UUID of the home cell of the principal whose
name is in question.
princ_idp
A pointer to the UUID of the principal whose name is in question.
Output
global_name
The global (full) name of the principal in sec_rgy_name_t form.
cell_namep
The name of the principal's home cell in sec_rgy_name_t form.
princ_namep
The local (with respect to the home cell) name of the principal in
sec_rgy_name_t form.
status
A pointer to the completion status. On successful completion, the
function returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_id_gen_name() routine generates a global name from input cell
and principal UUIDs. For example, given a UUID specifying the
cell /.../world/hp/brazil, and a UUID specifying a principal resident
in that cell named writers/tom, the routine would return the global name
of that principal, in this case, /.../world/hp/brazil/writers/tom. It
also returns the simple names of the cell and principal, translated from
the UUIDs.
The routine will not produce translations to any name for which a NULL
pointer has been supplied.
Permissions Required
The sec_id_gen_name() routine requires at least one permission of any
kind on the account associated with the input cell and principal UUIDs.
FILES
SYS$COMMON:[DCE$LIBRARY]SECIDMAP.IDL
The idl file from which dce/secidmap.h was derived.
ERRORS
sec_id_e_name_too_long
The name is too long for current implementation.
sec_id_e_bad_cell_uuid
The cell UUID is not valid.
sec_rgy_object_not_found
The registry server could not find the specified principal.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_id_gen_group
sec_id_parse_group
sec_id_parse_name
46 – sec_id_parse_group
NAME
sec_id_parse_group - Translates a global name into group and cell
names and UUIDs
SYNOPSIS
#include <dce/secidmap.h>
void sec_id_parse_group(
sec_rgy_handle_t context,
sec_rgy_name_t global_name,
sec_rgy_name_t cell_namep,
uuid_t *cell_idp,
sec_rgy_name_t group_namep,
uuid_t *group_idp,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
global_name
The global (full) name of the group in sec_rgy_name_t form.
Output
cell_namep
The output name of the group's home cell in sec_rgy_name_t form.
cell_idp
A pointer to the UUID of the home cell of the group whose name
is in question.
group_namep
The local (with respect to the home cell) name of the group in
sec_rgy_name_t form.
group_idp
A pointer to the UUID of the group whose name is in question.
status
A pointer to the completion status. On successful completion, the
function returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_id_parse_group() routine translates a global group name into
a cell name and a cell-relative group name. It also returns the UUIDs
associated with the group and its home cell.
The routine will not produce translations to any name for which a NULL
pointer has been supplied.
FILES
SYS$COMMON:[DCE$LIBRARY]SECIDMAP.IDL
The idl file from which dce/secidmap.h was derived.
ERRORS
sec_id_e_name_too_long
The name is too long for current implementation.
sec_id_e_bad_cell_uuid
The cell UUID is not valid.
sec_rgy_object_not_found
The registry server could not find the specified group.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_id_gen_group
sec_id_gen_name
sec_id_parse_group
sec_id_parse_name
47 – sec_id_parse_name
NAME
sec_id_parse_name - Translates a global name into principal and
cell names and UUIDs
SYNOPSIS
#include <dce/secidmap.h>
void sec_id_parse_name(
sec_rgy_handle_t context,
sec_rgy_name_t global_name,
sec_rgy_name_t cell_namep,
uuid_t *cell_idp,
sec_rgy_name_t princ_namep,
uuid_t *princ_idp,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
global_name
The global (full) name of the principal in sec_rgy_name_t form.
Output
cell_namep
The output name of the principal's home cell in sec_rgy_name_t
form.
cell_idp
A pointer to the UUID of the home cell of the principal whose name
is in question.
princ_namep
The local (with respect to the home cell) name of the principal
in sec_rgy_name_t form.
princ_idp
A pointer to the UUID of the principal whose name is in question.
status
A pointer to the completion status. On successful completion, the
function returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_id_parse_name() routine translates a global principal name into
a cell name and a cell-relative principal name. It also returns the
UUIDs associated with the principal and its home cell.
The routine will not produce translations to any name for which a NULL
pointer has been supplied.
Permissions Required
Only if princ_idp is requested as output does the sec_id_parse_name()
routine require a permission. In this case, the routine requires at
least one permission of any kind on the account whose global principal
name is to be translated.
FILES
SYS$COMMON:[DCE$LIBRARY]SECIDMAP.IDL
The idl file from which dce/secidmap.h was derived.
ERRORS
sec_id_e_name_too_long
The name is too long for current implementation.
sec_id_e_bad_cell_uuid
The cell UUID is not valid.
sec_rgy_object_not_found
The registry server could not find the specified principal.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_id_gen_name
48 – sec_key_mgmt_change_key
NAME
sec_key_mgmt_change_key - Changes a principal's key
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_change_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
unsigned32 key_vno,
void *keydata,
sec_timeval_period_t *garbage_collect_time,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine.
A value of NULL specifies that the default key file
(DCE$LOCAL:[KRB]V5SRVTAB.;) should be used. A key file name
specifies that file should be used as the key file. You must
prepend the file's absolute filename with FILE: and the file
must have been created with the rgy_edit ktadd command or the
sec_key_mgmt_set_key function.
Any other value specifies an argument for the get_key_fn key
acquisition routine. See the rpc_server_register_auth_info
reference page for more information.
principal_name
A pointer to a character string indicating the name of the
principal whose key is to be changed.
key_vno
The version number of the new key. If 0 (zero) is specified,
the routine will select the next appropriate key version number.
keydata
A pointer to a structure of type sec_passwd_rec_t.
Output
garbage_collect_time
The number of seconds that must elapse before all currently
valid tickets (which are encoded with the current or previous
keys) expire. At that time, all obsolete keys may be "garbage
collected", since no valid tickets encoded with those keys will
remain outstanding on the network.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_change_key() routine performs all activities necessary
to update a principal's key to the specified value. This includes
updating any local storage for the principal's key and also performing
any remote operations needed to keep the authentication protocol (or
network registry) current. Old keys for the principal are garbage
collected if appropriate.
FILES
The idl file from which dce/keymgmt.h was derived.
ERRORS
Any error condition will leave the key state unchanged.
sec_key_mgmt_e_key_unavailable
The old key is not present and therefore cannot be used
to set a client side authentication context.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_auth_unavailable
The authentication protocol is not available to update
the network database or to obtain the necessary network
credentials.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
sec_key_mgmt_e_key_unsupported
The key type is not supported.
sec_key_mgmt_e_key_version_ex
A key with this version number already exists.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
sec_rgy_object_not_found
No principal was found with the given name.
sec_login_s_no_memory
A memory allocation error occurred.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_generate_key
sec_key_mgmt_set_key
49 – sec_key_mgmt_delete_key
NAME
sec_key_mgmt_delete_key - Deletes a key from the local storage
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_delete_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
unsigned32 key_vno,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine.
A value of NULL specifies that the default key file
(DCE$LOCAL:[KRB]V5SRVTAB.;) should be used. A key file name
specifies that file should be used as the key file. You must
prepend the file's absolute filename with FILE: and the file
must have been created with the rgy_edit ktadd command or the
sec_key_mgmt_set_key function. Any other value specifies an
argument for the get_key_fn key acquisition routine. See the
rpc_server_register_auth_info() reference page for more
information.
principal_name
A pointer to a character string indicating the name of the
principal whose key is to be deleted.
key_vno
The version number of the desired key.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_delete_key() routine deletes the specified key from
the local key store. If an administrator ever discovers or suspects that
the security of a server's key has been compromised, the administrator
should delete the key immediately with sec_key_mgmt_delete_key(). This
routine removes the key from the local key storage, which invalidates
all extant tickets encoded with the key. If the compromised key is the
current one, the principal should change the key with
sec_key_mgmt_change_key() before deleting it. It is not an error for a
process to delete the current key (as long as it is done after the
network context has been established), but it may seriously
inconvenience legitimate clients of a service.
This routine deletes all key types that have the specified key version
number. A key type identifies the data encryption algorithm being used
(for example, DES). This routine differs from
sec_key_mgmt_delete_key_type() in that sec_key_mgmt_delete_key_type()
deletes only the specified key version of the specified key type from
the local key store.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
Any error condition will leave the key state unchanged.
sec_key_mgmt_e_key_unavailable
The requested key is not present.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_delete_key_type
sec_key_mgmt_garbage_collect
50 – sec_key_mgmt_delete_key_type
NAME
sec_key_mgmt_delete_key_type - Deletes a key version of a key
type from the local key storage
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_delete_key_type(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
void *keytype,
unsigned32 key_vno,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine. A value of NULL
specifies that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;)
should be used. A key file name specifies that file should be
used as the key file. You must prepend the file's absolute
filename with FILE: and the file must have been created with
the rgy_edit ktadd command or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the get_key_fn key
acquisition routine. See the rpc_server_register_auth_info()
reference page for more information.
principal_name
A pointer to a character string indicating the name of the
principal whose key type is to be deleted.
keytype
A pointer to a value of type sec_passwd_type_t. The value
identifies the data encryption algorithm that is being used
(for example, DES).
key_vno
The version number of the desired key.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_delete_key_type() routine deletes the specified key
version of the specified key type from the local key store. It differs
from sec_key_mgmt_delete_key() in that sec_key_mgmt_delete_key()
deletes all key types that have the same key version number.
This routine removes the key from the local key storage, which
invalidates all extant tickets encoded with the key. If the key in
question is the current one, the principal should change the key with
sec_key_mgmt_change_key() before deleting it. It is not an error for
a process to delete the current key (as long as it is done after the
network context has been established), but it may seriously
inconvenience legitimate clients of a service.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
Any error condition will leave the key state unchanged.
sec_key_mgmt_e_key_unavailable
The requested key is not present.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_delete_key
sec_key_mgmt_garbage_collect
51 – sec_key_mgmt_free_key
NAME
sec_key_mgmt_free_key - Frees the memory used by a key value
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_free_key(
void *keydata,
error_status_t *status);
PARAMETERS
Input
keydata
A pointer to a structure of type sec_passwd_rec_t.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok.
DESCRIPTION
The sec_key_mgmt_free_key() routine releases any storage allocated for
the indicated key data by sec_key_mgmt_get_key(). The storage for the
key data returned by sec_key_mgmt_get_key() is dynamically allocated.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_get_key
52 – sec_key_mgmt_garbage_collect
NAME
sec_key_mgmt_garbage_collect - Deletes obsolete keys
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_garbage_collect(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine. A value of NULL
specifies that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;)
should be used. A key file name specifies that file should be
used as the key file. You must prepend the file's absolute
filename with FILE: and the file must have been created with
the rgy_edit ktadd command or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the get_key_fn key
acquisition routine. See the rpc_server_register_auth_info()
reference page for more information.
principal_name
A pointer to a character string indicating the name of the
principal whose key information is to be garbage collected.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_garbage_collect() routine discards any obsolete key
information for this principal. An obsolete key is one that can only
decode invalid tickets. As an example, consider a key that was in use
on Monday, and was only used to encode tickets whose maximum lifetime
was 1 day. If that key was changed at 8:00 a.m. Tuesday morning, then
it would become obsolete by 8:00 a.m. Wednesday morning, at which time
there could be no valid tickets outstanding.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
Requested key not present.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
sec_rgy_object_not_found
No principal was found with the given name.
sec_login_s_no_memory
A memory allocation error occurred.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_delete_key
53 – sec_key_mgmt_gen_rand_key
NAME
sec_key_mgmt_gen_rand_key - Generates a new random key of a specified
key type
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_gen_rand_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
void *keytype,
unsigned32 key_vno,
void **keydata,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine. A value of NULL
specifies that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;)
should be used. A key file name specifies that file should be
used as the key file. You must prepend the file's absolute
filename with FILE: and the file must have been created with
the rgy_edit ktadd command or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the get_key_fn key
acquisition routine. See the rpc_server_register_auth_info()
reference page for more information.
principal_name
A pointer to a character string indicating the name of the
principal for whom the key is to be generated.
keytype
A pointer to a value of type sec_passwd_type_t. The value
identifies the data encryption algorithm to be used for the key
(for example, DES).
key_vno
The version number of the new key.
Output
keydata
A pointer to a value of sec_passwd_rec_t. The storage for keydata
is allocated dynamically, so the returned pointer actually
indicates a pointer to the key value. The storage for this data
may be freed with the sec_key_mgmt_free_key() function.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_gen_rand_key() routine generates a new random key
for a specified principal and of a specified key type. The generated
key can be used with the sec_key_mgmt_change_key() and
sec_key_mgmt_set_key() routines.
Note that to initialize the random keyseed, the process must first
make an authenticated call such as sec_rgy_site_open().
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_key_mgmt_e_not_implemented
The specified keytype is not supported.
sec_s_no_key_seed
No random key seed has been set.
sec_s_no_memory
Unable to allocate memory.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_change_key
sec_key_mgmt_generate_key
sec_key_mgmt_set_key
54 – sec_key_mgmt_get_key
NAME
sec_key_mgmt_get_key - Retrieves a key from local storage
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_get_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
unsigned32 key_vno,
void **keydata,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine. A value of NULL specifies
that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be
used. A key file name specifies that file should be used as the
key file. You must prepend the file's absolute filename with
FILE: and the file must have been created with the rgy_edit ktadd
command or the sec_key_mgmt_set_key routine. Any other value
specifies an argument for the get_key_fn key acquisition routine.
See the rpc_server_register_auth_info() reference page for more
information.
principal_name
A pointer to a character string indicating the name of the
principal to whom the key belongs.
key_vno
The version number of the desired key. To return the latest
version of the key, set this parameter to sec_c_key_version_none.
Output
keydata
A pointer to a value of type sec_passwd_rec_t. The storage for
keydata is allocated dynamically, so the returned pointer
actually indicates a pointer to the key value. The storage for
this data may be freed with the sec_key_mgmt_free_key() routine.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_get_key() routine extracts the specified key from
the local key store.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_key_mgmt_e_key_unavailable
The requested key is not present.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
sec_s_no_memory
Unable to allocate memory.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
55 – sec_key_mgmt_get_next_key
NAME
sec_key_mgmt_get_next_key - Retrieves successive keys from the local
key storage
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_get_next_key(
void *cursor,
idl_char **principal_name,
unsigned32 *key_vno,
void **keydata,
error_status_t *status);
PARAMETERS
Input
cursor
A pointer to the current cursor position in the local key
storage. The cursor position is set via the routine
sec_key_mgmt_initialize_cursor().
Output
principal_name
A pointer to a character string indicating the name of the
principal associated with the extracted key. Free the storage
for the principal name with the free() function.
key_vno
The version number of the extracted key.
keydata
A pointer to a value of type sec_passwd_rec_t. The storage for
keydata is allocated dynamically, so the returned pointer
actually indicates a pointer to the key value. The storage for
this data may be freed with the sec_key_mgmt_free_key() function.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_get_next_key() routine extracts the key pointed to by
the cursor in the local key store and updates the cursor to point to the
next key. By repeatedly calling this routine you can scan all the keys
in the local store.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_key_mgmt_e_key_unavailable
The requested key is not present.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
sec_s_no_memory
Unable to allocate memory.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_get_key
sec_key_mgmt_initialize_cursor
56 – sec_key_mgmt_get_next_kvno
NAME
sec_key_mgmt_get_next_kvno - Retrieves the next eligible key version
number for a key
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_get_next_kvno(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
void *keytype,
unsigned32 *key_vno,
unsigned32 *next_key_vno,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine. A value of NULL specifies
that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be
used. A key file name specifies that file should be used as the
key file. You must prepend the file's absolute filename with
FILE: and the file must have been created with the rgy_edit ktadd
command or the sec_key_mgmt_set_key routine. Any other value
specifies an argument for the get_key_fn key acquisition routine.
See the rpc_server_register_auth_info() reference page for more
information.
principal_name
A pointer to a character string indicating the name of the
principal associated with the key.
keytype
A pointer to a value of type sec_passwd_type_t. The value
identifies the data encryption algorithm (for example, DES)
being used for the key.
Output
key_vno
The current version number of the key. Specify NULL if you do
not need this value to be returned.
next_key_vno
The next eligible version number for the key. Specify NULL if
you do not need this value to be returned.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_get_next_kvno() routine returns the current and next
eligible version numbers for a key from the registry server (not from
the local key table). The key is identified via its associated
authentication protocol, principal name, and key type. The arg value
associated with the key is also specified.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_key_mgmt_e_key_unavailable
The requested key is not present.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
sec_rgy_object_not_found
No principal was found with the given name.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
57 – sec_key_mgmt_initialize_cursor
NAME
sec_key_mgmt_initialize_cursor - Repositions the cursor in the local
key store
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_initialize_cursor(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
void *keytype,
void **cursor,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine. A value of NULL specifies
that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be
used. A key file name specifies that file should be used as the
key file. You must prepend the file's absolute filename with
FILE: and the file must have been created with the rgy_edit ktadd
command or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the get_key_fn key
acquisition routine. See the rpc_server_register_auth_info()
reference page for more information.
principal_name
A pointer to a character string indicating the name of the
principal whose key is to be accessed. To access all keys in
the local key store, supply NULL for this parameter.
keytype
A pointer to the data encryption algorithm (for example, DES)
being used for the key.
Output
cursor
The returned cursor value. The storage for the cursor information
is allocated dynamically, so the returned pointer actually
indicates a pointer to the cursor value. The storage for this
data may be freed with the sec_key_mgmt_release_cursor() routine.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_initialize_cursor() routine resets the cursor in the
local key store.
Use this routine to reposition the cursor before performing a scan of
the local store via sec_key_mgmt_get_next_key(). The returned cursor
value is supplied as input to sec_key_mgmt_get_next_key().
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_s_no_memory
Unable to allocate memory.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_get_next_key
sec_key_mgmt_release_cursor
58 – sec_key_mgmt_manage_key
NAME
sec_key_mgmt_manage_key - Automatically changes a principal's key
before it expires
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_manage_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine. A value of NULL specifies
that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be
used. A key file name specifies that file should be used as the
key file. You must prepend the file's absolute filename with
FILE: and the file must have been created with the rgy_edit ktadd
command or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the get_key_fn key
acquisition routine. See the rpc_server_register_auth_info()
reference page for more information.
principal_name
A pointer to a character string indicating the name of the
principal whose key is to be managed.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_manage_key() routine changes the specified principal's
key on a regular basis, as determined by the local cell's policy. It
will run indefinitely, never returning during normal operation, and
therefore should be invoked only from a thread that has been devoted to
managing keys.
This routine queries the DCE Registry to determine the password
expiration policy that applies to the named principal. It then idles
until a short time before the current key is due to expire and then uses
the sec_key_mgmt_gen_rand_key() to produce a new random key, updating
both the local key store and the DCE Registry. This routine also
invokes sec_key_mgmt_garbage_collect() as needed.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_key_mgmt_e_key_unavailable
The old key is not present and therefore cannot be used to
set a client side authentication context.
sec_key_mgmt_e_key_unsupported
The key type is not supported.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
sec_rgy_object_not_found
No principal was found with the given name.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_gen_rand_key
sec_key_mgmt_garbage_collect
59 – sec_key_mgmt_release_cursor
NAME
sec_key_mgmt_release_cursor - Releases the memory used by an
initialized cursor value
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_release_cursor(
void **cursor,
error_status_t *status);
PARAMETERS
Input
cursor
A pointer to the cursor value for which the storage is to be
released.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok.
DESCRIPTION
The sec_key_mgmt_release_cursor() routine releases any storage
allocated for the indicated cursor value by
sec_key_mgmt_initialize_cursor(). The storage for the cursor value
returned by sec_key_mgmt_initialize_cursor() is dynamically allocated.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_initialize_cursor
60 – sec_key_mgmt_set_key
NAME
sec_key_mgmt_set_key - Inserts a key value into the local storage
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_set_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
unsigned32 key_vno,
void *keydata,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine. A value of NULL specifies
that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be
used. A key file name specifies that file should be used as the
key file. The file name must begin with FILE:. If the file name
does not begin with FILE:, the code will add it. Any other value
specifies an argument for the get_key_fn key acquisition routine.
See the rpc_server_register_auth_info() reference page for more
information.
principal_name
A pointer to a character string indicating the name of the
principal associated with the key to be set.
key_vno
The version number of the key to be set.
keydata
A pointer to the key value to be set.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_set_key() routine performs all local activities
necessary to update a principal's key to the specified value. This
routine will not update the authentication protocol's value for the
principal's key.
In some circumstances, a server may only wish to change its key in the
local key storage, and not in the DCE Registry. For example, a
database system may have several replicas of a master database, managed
by servers running on independent machines. Since these servers together
represent only one service, they should all share the same key. This
way, a user with a ticket to use the database can choose whichever
server is least busy. To change the database key, the master server
would signal all the replica (slave) servers to change the current key
in their local key storage. They would use the sec_key_mgmt_set_key()
routine, which does not communicate with the DCE Registry. Once all the
slaves have complied, the master server can then change the Registry key
and its own local storage.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_key_mgmt_e_key_unavailable
The old key is not present and therefore cannot be used to
set a client side authentication context.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
sec_key_mgmt_e_key_unsupported
The key type is not supported.
sec_key_mgmt_e_key_version_ex
A key with this version number already exists.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_change_key
sec_key_mgmt_gen_rand_key
61 – sec_login_become_delegate
NAME
sec_login_become_delegate - Causes an intermediate server to become a
delegate in traced delegation chain
SYNOPSIS
#include <dce/sec_login.h>
sec_login_handle_t sec_login_become_delegate(
rpc_authz_cred_handle_t callers_identity,
sec_login_handle_t my_login_context,
sec_id_delegation_type_t delegation_type_permitted,
sec_id_restriction_set_t *delegate_restrictions,
sec_id_restriction_set_t *target_restrictions,
sec_id_opt_req_t *optional_restrictions,
sec_id_opt_req_t *required_restrictions,
sec_id_compatibility_mode_t compatibility_mode,
error_status_t *status);
PARAMETERS
Input
callers_identity
A handle of type rpc_authz_cred_handle_t to the authenticated
identity of the previous delegate in the delegation chain. The
handle is supplied by the rpc_binding_inq_auth_caller() call.
my_login_context
A value of sec_login_handle_t that provides an opaque handle to
the identity of the client that is becoming the intermediate
delegate. The sec_login_handle_t that specifies the client's
identity is supplied as output of the following calls:
+ sec_login_get_current_context() if the client inherited the
identity of the current context
+ The sec_login_setup_identity() and the
sec_login_validate_identity() pair that together establish
an authenticated identity if a new identity was established
Note that this identity specified by sec_login_handle_t must be a simple
login context; it cannot be a compound identity created by a previous
sec_login_become_delegate() call.
delegation_type_permitted
A value of sec_id_delegation_type_t that specifies the type of
delegation to be enabled. The types available are:
sec_id_deleg_type_none
No delegation.
sec_id_deleg_type_traced
Traced delegation.
sec_id_deleg_type_impersonation
Simple (impersonation) delegation.
Note that the initiating client sets the type of delegation. If it is
set as traced, all delegates must also specify traced delegation; they
cannot specify simple delegation. The same is true if the initiating
client sets the delegation type as simple; all subsequent delegates must
also specify simple delegation. The intermediate delegates can,
however, specify no delegation to indicate that the delegation chain
can proceed no further.
delegate_restrictions
A pointer to a sec_id_restriction_set_t that supplies a list of
servers that can act as delegates for the intermediate client
identified by my_login_context. These servers are added to
delegates permitted by the delegate_restrictions parameter of the
sec_login_become_initiator call.
target_restrictions
A pointer to a sec_id_restriction_set_t that supplies a list of
servers that can act as targets for the intermediate client
identified by my_login_context. These servers are added to
targets specified by the target_restrictions parameter of the
sec_login_become_initiator call.
optional_restrictions
A pointer to a sec_id_opt_req_t that supplies a list of
application-defined optional restrictions that apply to the
intermediate client identified by my_login_context. These
restrictions are added to the restrictions identified by the
optional_restrictions parameter of the sec_login_become_initiator
call.
required_restrictions
A pointer to a sec_id_opt_req_t that supplies a list of
application-defined required restrictions that apply to the
intermediate client identified by my_login_context. These
restrictions are added to the restrictions identified
required_restrictions parameter of the sec_login_become_initiator
call.
compatibility_mode
A value of sec_id_compatibility_mode_t that specifies the
compatibility mode to be used when the intermediate client
operates on pre-1.1 servers. The modes available are:
sec_id_compat_mode_none
Compatibility mode is off.
sec_id_compat_mode_initiator
Compatibility mode is on. The pre-1.1 PAC data is
extracted from the EPAC of the initiating client.
sec_id_compat_mode_caller
Compatibility mode is on. The pre-1.1 PAC data
extracted from the EPAC of the last client in the
delegation chain.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_become_delegate() is used by intermediate servers to
become a delegate for the client identified by callers_identity. The
routine returns a new login context (of type sec_login_handle_t) that
carries delegation information. This information includes the delegation
type, delegate and target restrictions, and any application-defined
optional and required restrictions.
The new login context created by this call can then used to to set up
authenticated rpc with an intermediate or target server using the
rpc_binding_set_auth_info() call.
Any delegate, target, required, or optional restrictions specified in
this call are added to the restrictions specified by the initiating
client and any intermediate clients.
The sec_login_become_delegate() call is run only if the initiating
client enabled traced delegation by setting the
delegation_type_permitted parameter in the sec_login_become_initiator
call to sec_id_deleg_type_traced.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_invalid_context
sec_login_s_compound_delegate
sec_login_s_invalid_deleg_type
err_sec_login_invalid_delegate_restriction
err_sec_login_invalid_target_restriction
err_sec_login_invalid_opt_restriction
err_sec_login_invalid_req_restriction
sec_login_s_invalid_compat_mode
sec_login_s_deleg_not_enabled
error_status_ok
RELATED INFORMATION
Functions: intro
sec_login_become_initiator
sec_login_become_impersonator
rpc_binding_inq_auth_caller
sec_login_get_current_context
sec_login_setup_identity
sec_login_validate_identity
62 – sec_login_become_impersonator
NAME
sec_login_become_impersonator - Causes an intermediate server to
become a delegate in a simple
delegation chain
SYNOPSIS
#include <dce/sec_login.h>
sec_login_handle_t sec_login_become_impersonator(
rpc_authz_cred_handle_t callers_identity,
sec_id_delegation_type_t delegation_type_permitted,
sec_id_restriction_set_t *delegate_restrictions,
sec_id_restriction_set_t *target_restrictions,
sec_id_opt_req_t *optional_restrictions,
sec_id_opt_req_t *required_restrictions,
error_status_t *status);
PARAMETERS
Input
callers_identity
A handle of type rpc_authz_cred_handle_t to the authenticated
identity of the previous delegate in the delegation chain. The
handle is supplied by the rpc_binding_inq_auth_caller() call.
delegation_type_permitted
A value of sec_id_delegation_type_t that specifies the type of
delegation to be enabled. The types available are:
sec_id_deleg_type_none
No delegation.
sec_id_deleg_type_traced
Traced delegation.
sec_id_deleg_type_impersonation
Simple (impersonation) delegation.
The initiating client sets the type of delegation. If it is set as
traced, all delegates must also specify traced delegation; they cannot
specify simple delegation. The same is true if the initiating client
sets the delegation type as simple; all subsequent delegates must also
specify simple delegation. The intermediate delegates can, however,
specify no delegation to indicate that the delegation chain can proceed
no further.
delegate_restrictions
A pointer to a sec_id_restriction_set_t that supplies a list of
servers that can act as delegates for the client becoming the
delegate. These servers are added to the delegates permitted by
the delegate_restrictions parameter of the
sec_login_become_initiator call.
target_restrictions
A pointer to a sec_id_restriction_set_t that supplies a list of
servers that can act as targets for the client becoming the
delegate. These servers are added to targets specified by the
target_restrictions parameter of the sec_login_become_initiator
call.
optional_restrictions
A pointer to a sec_id_opt_req_t that supplies a list of
application-defined optional restrictions that apply to the
client becoming the delegate. These restrictions are added to
the restrictions identified by the optional_restrictions
parameter of the sec_login_become_initiator call.
required_restrictions
A pointer to a sec_id_opt_req_t that supplies a list of
application-defined required restrictions that apply to the
client becoming the delegate. These restrictions are added to
the restrictions identified required_restrictions parameter of
the sec_login_become_initiator call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_become_impersonator() is used by intermediate servers to
become a delegate for the client identified by callers_identity. The
routine returns a new login context (of type sec_login_handle_t) that
carries delegation information. This information includes the delegation
type, delegate, and target restrictions, and any application-defined
optional and required restrictions.
The new login context created by this call can then used to to set up
authenticated rpc with an intermediate or target server using the
rpc_binding_set_auth_info() call.
The effective optional and required restrictions are the union of the
optional and required restrictions specified in this call and specified
by the initiating client and any intermediate clients. The effective
target and delegate restrictions are the intersection of the target
and delegate restrictions specified in this call and specified by the
initiating client and any intermediate clients.
The sec_login_become_impersonator call is call is run only if the
initiating client enabled simple delegation by setting the
delegation_type_permitted parameter in the sec_login_become_initiator
call to sec_id_deleg_type_simple.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_invalid_deleg_type
err_sec_login_invalid_delegate_restriction
err_sec_login_invalid_target_restriction
err_sec_login_invalid_opt_restriction
err_sec_login_invalid_req_restriction
sec_login_s_invalid_compat_mode
sec_login_s_deleg_not_enabled
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_login_become_initiator
rpc_binding_inq_auth_caller
63 – sec_login_become_initiator
NAME
sec_login_become_initiator - Constructs a new login context that
enables delegation for the calling client
SYNOPSIS
#include <dce/sec_login.h>
sec_login_handle_t sec_login_become_initiator(
sec_login_handle_t my_login_context,
sec_id_delegation_type_t delegation_type_permitted,
sec_id_restriction_set_t *delegate_restrictions,
sec_id_restriction_set_t *target_restrictions,
sec_id_opt_req_t *optional_restrictions,
sec_id_opt_req_t *required_restrictions,
sec_id_compatibility_mode_t compatibility_mode,
error_status_t *status);
PARAMETERS
Input
my_login_context
A value of sec_login_handle_t that provides an opaque handle to
the identity of the client that is enabling delegation. The
sec_login_handle_t that specifies the client's identity is
supplied as output of the following calls:
+ sec_login_get_current_context() if the client inherited the
identity of the current context
+ The sec_login_setup_identity() and the
sec_login_validate_identity() pair that together establish
an authentiated identity if a new identity was established
delegation_type_permitted
A value of sec_id_delegation_type_t that specifies the type of
delegation to be enabled. The types available are:
sec_id_deleg_type_none
No delegation.
sec_id_deleg_type_traced
Traced delegation.
sec_id_deleg_type_impersonation
Simple (impersonation) delegation.
Note each subsequent intermediate delegate of the delegation chain
started by the initiating client must set the delegation type to traced
if the initiating client set it to traced or to simple if the
initiating client set it to simple. Intermediate delegates, however,
can set the delegation type to no delegation to indicate that the
delegation chain can proceed no further.
delegate_restrictions
A pointer to a sec_id_restriction_set_t that supplies a list
of servers that can act as delegates for the client initiating
delegation.
target_restrictions
A pointer to a sec_id_restriction_set_t that supplies a list
of servers that can act as targets for the client initiating
delegation.
optional_restrictions
A pointer to a sec_id_opt_req_t that supplies a list of
application-defined optional restrictions that apply to the
client initiating delegation.
required_restrictions
A pointer to a sec_id_opt_req_t that supplies a list of
application-defined required restrictions that apply to the
client initiating delegation.
compatibility_mode
A value of sec_id_compatibility_mode_t that specifies the
compatibility mode to be used when the initiating client
interacts with pre-1.1 servers. The modes available are:
sec_id_compat_mode_none
Compatibility mode is off.
sec_id_compat_mode_initiator
Compatibility mode is on. The pre-1.1 PAC data is
extracted from the EPAC of the initiating client.
sec_id_compat_mode_caller
Compatibility mode is on. The pre-1.1 PAC data
extracted from the EPAC of the last client in the
delegation chain.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_become_initiator() enables delegation for the calling
client by constructing a new login context (in a sec_login_handle_t)
that carries delegation information. This information includes the
delegation type, delegate, and target restrictions, and any
application-defined optional and required restrictions.
The new login context is then used to to set up authenticated rpc with
an intermediate server using the rpc_binding_set_auth_info() call. The
intermediary can continue the delegation chain by calling
sec_login_become_delegate (if the delegation type is
sec_id_deleg_type_traced) or sec_login_become_impersonator (if the
delegation type is sec_id_deleg_type_impersonation).
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_invalid_context
sec_login_s_invalid_deleg_type
err_sec_login_invalid_delegate_restriction
err_sec_login_invalid_target_restriction
err_sec_login_invalid_opt_restriction
err_sec_login_invalid_req_restriction
sec_login_s_invalid_compat_mode
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_login_become_delegate
sec_login_become_impersonator
sec_login_get_current_context
sec_login_setup_identity
sec_login_validate_identity
64 – sec_login_certify_identity
NAME
sec_login_certify_identity - Certifies the network
authentication service
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_certify_identity(
sec_login_handle_t login_context,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and UUID,
account restrictions, records of group membership, and the
process home directory. (See sec_intro for more details about
the login context.)
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_certify_identity() routine certifies that the Security
Server used to set up and validate a login context is legitimate. A
legitimate server is one that knows the host machine's secret key.
On some systems, this may be a privileged operation.
Information may be retrieved via sec_login_get_pwent(),
sec_login_get_groups(), and sec_login_get_expiration() from an
uncertified login context, but such information cannot be trusted.
All system login programs that use the sec_login interface must call
sec_login_certify_identity() to certify the Security Server. If they
do not, they open the local file system to attacks by imposter Security
servers returning suspect local process credentials (UUID and group
IDs). This operation updates the local registry with the login context
credentials if the certification check succeeds.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
RETURN VALUES
The routine returns a boolean32 value that is TRUE if the certification
was successful, and FALSE otherwise.
ERRORS
sec_login_s_config
The DCE configuration (dce_config) information is not
available.
sec_login_s_context_invalid
The input context is invalid.
sec_login_s_default_use
It is an error to try to certify the default context.
error_status_ok
The call was successful.
EXAMPLES
Applications wishing to perform a straightforward login could use the
sec_login package as follows:
if (sec_login_setup_identity(user_name, sec_login_no_flags,
&login_context, &st)) {
... get password from user...
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
if (!sec_login_certify_identity(login_context, &st))
exit(error_weird_auth_svc);
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
if (reset_passwd) {
... get new password from user, reset registry record ...
};
sec_login_get_pwent(login_context, &pw_entry, &st);
if (pw_entry.pw_expire < todays_date) {
sec_login_purge_context(&login_context, &st);
exit(0)
}
... any other application specific login valid actions ...
}
} else {
sec_login_purge_context(&login_context, &st);
... application specific login failure actions ...
}
}
RELATED INFORMATION
Functions: sec_intro,
sec_login_get_pwent
sec_login_get_groups
sec_login_get_expiration
65 – sec_login_cred_get_delegate
NAME
sec_login_cred_get_delegate - Returns a handle to the privilege
attributes of an intermediary in a
delegation chain
Used by clients.
SYNOPSIS
#include <dce/sec_login.h>
sec_cred_pa_handle_t sec_login_cred_get_delegate(
sec_login_handle_t login_context,
sec_cred_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input
login_context
A value of sec_login_handle_t that provides an opaque handle to
a login context for which delegation has been enabled. The
sec_login_handle_t that specifies the identity is supplied
as output of the sec_login_become_delegate() call.
Input/Output
cursor
As input, a pointer to a cursor of type sec_cred_cursor_t that
has been initialized by the sec_login_cred_init_cursor() call.
As an output parameter, cursor is a pointer to a cursor of type
sec_cred_cursor_t that is positioned past the principal whose
privilege attributes have been returned in this call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_cred_get_delegate() routine returns a handle of type
sec_login_handle_t to the the privilege attributes of an intermediary
in a delegation chain that performed an authenticated RPC operation.
This call is used by clients. Servers use the sec_cred_get_delegate()
routine to return the privilege attribute handle of an intermediary in
a delegation chain.
The login context identified by login_context contains all members in
the delegation chain. This call returns a handle (sec_cred_pa_handle_t)
to the privilege attributes of one of the delegates in the login
context. The sec_cred_pa_handle_t returned by this call is used in
other sec_cred_get... calls to obtain privilege attribute information
for a single delegate.
To obtain the privilege attributes of each delegate in the credential
handle identified by callers_identity, execute this call until the
message sec_cred_s_no_more_entries is returned.
Before you execute sec_login_cred_get_delegate(), you must execute a
sec_login_cred_init_cursor() call to initialize a cursor of type
sec_cred_cursor_t.
Use the sec_cred_free_pa_handle() sec_cred_free_cursor() calls to free
the resources allocated to the sec_cred_pa_handle_t and cursor.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_cred_s_invalid_cursor
sec_cred_s_no_more_entries
error_status_ok
EXAMPLES
RELATED INFORMATION
Functions: sec_intro
sec_login_cred_init_cursor
sec_cred_get_pa_date
sec_cred_get_extended_attrs
sec_cred_get_v1_pac
sec_cred_get_tgt_restrictions
sec_cred_get_deleg_restrictions
sec_cred_get_opt_restrictions
sec_cred_get_req_restrictions
sec_cred_get_delegation_type
66 – sec_login_cred_get_initiator
NAME
sec_login_cred_get_initiator - Returns information about the
delegation initiator in a specified
login context
SYNOPSIS
#include <dce/sec_login.h>
sec_cred_pa_handle_t sec_login_cred_get_initiator(
sec_login_handle_t login_context,
error_status_t *status);
PARAMETERS
Input
login_context
A value of sec_login_handle_t that provides an opaque handle
to a login context for which delegation has been enabled.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_cred_get_initiator() routine returns a handle of type
sec_cred_pa_handle_t to the privilege attributes of the delegation
initiator.
The login context identified by login_context contains all members in
the delegation chain. This call returns a handle (sec_cred_pa_handle_t)
to the privilege attributes of the initiator. The sec_cred_pa_handle_t
returned by this call is used in other sec_cred_get... calls to obtain
privilege attribute information for the initiator single delegate.
Use the sec_cred_free_pa_handle() call to free the resources allocated
to the sec_cred_pa_handle_t handle.
FILES
SYS$LIBRARY:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_invalid_context
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_pa_date
sec_cred_get_extended_attrs
sec_cred_get_v1_pac
sec_cred_get_tgt_restrictions
sec_cred_get_deleg_restrictions
sec_cred_get_opt_restrictions
sec_cred_get_req_restrictions
sec_cred_get_delegation_type
67 – sec_login_cred_init_cursor
NAME
sec_login_cred_init_cursor - Initialize a sec_cred_cursor_t
SYNOPSIS
#include <dce/sec_cred.h>
void sec_login_cred_init_cursor (
sec_cred_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input/Output
cursor
As input, a pointer to a sec_cred_cursor_t to be initialized.
As output, a pointer to an initialized sec_cred_cursor_t.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_cred_init_cursor() routine allocates and initializes
a cursor of type sec_cursor_t for use with the
sec_login_cred_get_delegate() call.
Use the sec_cred_free_cursor() call to free the resources allocated to
cursor.
ERRORS
sec_cred_s_invalid_cursor
sec_login_s_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_login_cred_get_delegate
68 – sec_login_disable_delegation
NAME
sec_login_disable_delegation - Disables delegation for a specified
login context
SYNOPSIS
#include <dce/sec_login.h>
sec_logon_handle_t *sec_login_disable_delegation(
sec_login_handle_t login_context,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context for which delegation has been
enabled.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_disable_delegation() routine disables delegation for a
specified login context. It returns a new login context of type
sec_login_handle_t without any delegation information, thus preventing
any further delegation.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_invalid_context
error_status_ok
EXAMPLES
RELATED INFORMATION
Functions: sec_intro
sec_login_become_initiator
sec_login_become_delegate
sec_login_become_impersonator
69 – sec_login_export_context
NAME
sec_login_export_context - Creates an exportable login context
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_export_context(
sec_login_handle_t login_context,
unsigned32 buf_len,
idl_byte buf[],
unsigned32 *len_used,
unsigned32 *len_needed,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and UUID,
account restrictions, records of group membership, and the
process home directory. (See sec_intro for more details about
the login context.)
buf_len
An unsigned 32-bit integer containing the allocated length
(in bytes) of the buffer that is to contain the login context.
Output
buf[] An idl_byte array that contains the exportable login context upon
return.
len_used
A pointer to an unsigned 32-bit integer indicating the number of
bytes needed for the entire login context, up to buf_len.
len_needed
If the allocated length of the buffer is too short, an error is
issued (sec_login_s_no_memory), and on return this pointer
indicates the number of bytes necessary to contain the login
context.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_export_context() routine obtains an exportable version
of the login context information. This information may be passed to
another process running on the same machine.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_no_memory
Not enough space was allocated for the buf[] array. The
len_needed parameter will point to the needed length.
sec_login_s_handle_invalid
The login context handle is invalid.
sec_login_s_context_invalid
The login context specified by the input handle is
invalid.
RELATED INFORMATION
Functions: sec_intro
sec_login_import_context
70 – sec_login_free_net_info
NAME
sec_login_free_net_info - Frees storage allocated for a principal's
network information
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_free_net_info(
sec_login_net_info_t *net_info);
PARAMETERS
Input/Output
net_info
A pointer to the sec_login_net_info_t structure to be freed.
DESCRIPTION
The sec_login_free_net_info() routine frees any memory allocated for
a principal's network information. Network information is returned
by a previous successful call to sec_login_inquire_net_info().
CAUTIONS
This routine does not return any completion codes. Make sure that
you supply a valid sec_login_net_info_t address. The routine simply
frees a range of storage beginning at the supplied address, without
regard to the actual contents of the storage.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
RELATED INFORMATION
Functions: sec_intro
sec_login_inquire_net_info
71 – sec_login_get_current_context
NAME
sec_login_get_current_context - Returns a handle to the current
login context
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_get_current_context(
sec_login_handle_t *login_context,
error_status_t *status);
PARAMETERS
Output
login_context
A pointer to an opaque handle to login context data. The login
context contains, among other data, the account principal name
and UUID, account restrictions, records of group membership,
and the process home directory. (See sec_intro for more
details about the login context.)
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_get_current_context() routine retrieves a handle to the
login context for the currently established network identity. The
context returned is created from locally cached data so subsequent
data extraction operations may return some NULL values.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_no_current_context
There was no current context to retrieve. (See
sec_login_setup_identity for information about how
to set up, validate, and implement a login context.)
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the
sec_login_get_current_context() routine as part of a process to change
the groupset:
sec_login_get_current_context(&login_context, &st);
sec_login_get_groups(login_context, &num_groups, &groups, &st);
...the group IDs have to be converted from the returned UNIX
numbers into UUIDs (use sec_rgy_pgo_unix_num_to_id)...
for (i=0; i < num_groups; i++) {
... query whether the user wants to discard any of the current
group memberships. Copy new groupset to the new_groups array ...
}
if ( !sec_login_newgroups(sec_login_no_flags, num_new_groups,
new_groups, &login_context, &st)) {
if (st == sec_login_s_groupset_invalid)
printf("New groupset invalid0);
... application specific error handling ...
}
RELATED INFORMATION
Functions: sec_intro
sec_login_setup_identity
72 – sec_login_get_expiration
NAME
sec_login_get_expiration - Returns the TGT lifetime for an
authenticated identity
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_get_expiration(
sec_login_handle_t login_context,
signed32 *identity_expiration,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and
UUID, account restrictions, records of group membership, and
the process home directory. (See sec_intro for more details
about the login context.)
Output
identity_expiration
The lifetime of the Ticket-Granting Ticket (TGT) belonging to
the authenticated identity identified by login_context. It can
be used in the same ways as a UNIX time_t.
status
A pointer to the completion status. On successful completion,
the routine returns one of the following status codes:
+ error_status_ok to indicate that the login context has been
validated and certified.
+ sec_login_s_not_certified to indicate that the login context
has been validated, but not certified. Although this code
indicates successful completion, it warns you that the
context is not validated.
If the call does not complete successfully, it returns an error.
DESCRIPTION
The sec_login_get_expiration() routine extracts the lifetime for the
TGT belonging to the authenticated identity contained in the login
context. The liftime value is filled in if available; otherwise, it
is set to 0 (zero). This routine allows an application to tell an
interactive user how long the user's network login (and authenticated
identity) will last before having to be refreshed.
The routine works only on previously certified contexts.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_context_invalid
The login context itself is invalid.
sec_login_s_default_use
There was illegal use of the default login handle.
sec_login_s_not_certified
The login context has not been certified.
sec_login_s_no_current_context
The calling process has no context of its own.
error_status_ok
The call was successful.
EXAMPLES
Since the authenticated network identity for a process has a finite
lifetime, there is a risk it will expire during some long network
operation, preventing the operation from completing. To avoid this
situation, an application might, before initiating a long operation,
use the sec_login package to check the expiration time of its identity
and refresh it if there is not enough time remaining to complete the
operation. After refreshing the identity, the process must validate it
again with sec_login_validate_identity().
sec_login_get_expiration(login_context, &expire_time, &st);
if (expire_time < (current_time + operation_duration)) {
if (!sec_login_refresh_identity(login_context, &st)) {
if (st == sec_login_s_refresh_ident_bad) {
... identity has changed ...
} else {
... login context cannot be renewed ...
exit(error_context_not_renewable);
}
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
... identity validated ...
} else {
... validation failed ...
exit(error_validation_failure);
}
}
}
operation();
RELATED INFORMATION
Functions: sec_intro
sec_login_get_current_context
73 – sec_login_get_groups
NAME
sec_login_get_groups - Returns the groupset from a login context
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_get_groups(
sec_login_handle_t login_context,
unsigned32 *num_groups,
signed32 **group_set,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and UUID,
account restrictions, records of group membership, and the
process home directory. (See sec_intro for more details about
the login context.)
Output
num_groups
An unsigned 32-bit integer indicating the total number of groups
returned in the group_set array.
group_set
The list of groups to which the user belongs.
status
A pointer to the completion status. On successful completion,
the routine returns one of the following status codes:
+ error_status_ok to indicate that the login context has
been validated and certified.
+ sec_login_s_not_certified to indicate that the login context
has been validated, but not certified. Although this code
indicates successful completion, it warns you that the
context is not validated.
If the call does not complete successfully, it returns an error.
DESCRIPTION
The sec_login_get_groups() routine returns the groups contained in the
supplied login context. Part of a network identity is a list of the
various groups to which the principal belongs. The groups are used to
determine a user's access to various objects and services. This
routine extracts from the login context a list of the groups for which
the user has established network privileges.
The routine works only on previously validated contexts.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_context_invalid
The login context itself is not valid.
sec_login_s_info_not_avail
The login context has no UNIX information.
sec_login_s_default_use
Illegal use of the default login handle occurred.
sec_login_s_not_certified
The login context has not been certified.
sec_login_s_not_certified
The login context is not certified.
sec_rgy_object_not_found
The registry server could not find the specified
login context data.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the sec_login_get_groups()
routine as part of a process to change the groupset:
sec_login_get_current_context(&login_context, &st);
sec_login_get_groups(login_context, &num_groups, &groups, &st);
...the group IDs have to be converted from the returned UNIX
numbers into UUIDs (use sec_rgy_pgo_unix_num_to_id)...
for (i=0; i < num_groups; i++) {
... query whether the user wants to discard any of the current
group memberships. Copy new groupset to the new_groups array ...
}
if ( !sec_login_newgroups(sec_login_no_flags, num_new_groups,
new_groups, &login_context, &st)) {
if (st == sec_login_s_groupset_invalid)
printf("New groupset invalid0);
... application specific error handling ...
}
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_get_projlist
74 – sec_login_get_pwent
NAME
sec_login_get_pwent - Returns a passwd-style entry for a login context
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_get_pwent(
sec_login_handle_t login_context,
sec_login_passwd_t *pwent,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and UUID,
account restrictions, records of group membership, and the
process home directory. (See sec_intro for more details about
the login context.)
Output
pwent A pointer to a pointer to the returned passwd-style structure.
The particular structure depends on the underlying system. For
example, on a system with a passwd structure like that supported
by 4.4BSD and OSF/1, the structure (found in /usr/include/pwd.h)
is:
struct passwd {
char *pw_name; /* user name */
char *pw_passwd; /* encrypted password */
int pw_uid; /* user uid */
int pw_gid; /* user gid */
time_t pw_change; /* password change time */
char *pw_class; /* user access class */
char *pw_gecos; /* miscellaneous account info */
char *pw_dir; /* home directory */
char *pw_shell; /* default shell */
time_t pw_expire; /* account expiration */
};
status
A pointer to the completion status. On successful completion,
the routine returns one of the following status codes:
+ error_status_ok to indicate that the login context has
been validated and certified.
+ sec_login_s_not_certified to indicate that the login context
has been validated, but not certified. Although this code
indicates successful completion, it warns you that the
context is not validated.
If the call does not complete successfully, it returns an error.
DESCRIPTION
The sec_login_get_pwent() routine creates a passwd-style structure for
the current network login context. This is generally useful for
establishing the local operating system context. Applications that
require all of the data normally extracted via getpwnam() should extract
that data from the login context with this call.
This routine works only on explicitly created (not inherited or
imported) contexts.
CAUTIONS
The returned sec_login_passwd_t structure points to data stored in
the structure indicated by the login_context pointer and must be
treated as read-only data. Writing to these data objects may cause
unexpected failures.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
EXAMPLES
The following example illustrates use of the sec_login_get_pwent()
routine:
#include <pwd.h>
struct passwd *pwd;
sec_login_get_pwent( login_context,
&(sec_login_passwd_t*)pwd,&status );
printf ("%s",pwd->pw_name);
ERRORS
sec_login_s_context_invalid
The login context itself is invalid.
sec_login_s_not_certified
The login context has not been certified.
sec_login_s_default_use
Illegal use of the default login handle occurred.
sec_login_s_info_not_avail
The login context has no UNIX information.
sec_rgy_object_not_found
The registry server could not find the specified login
context data.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
75 – sec_login_import_context
NAME
sec_login_import_context - Imports a login context
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_import_context(
unsigned32 buf_len,
idl_byte buf[],
sec_login_handle_t *login_context,
error_status_t *status);
PARAMETERS
Input
buf_len
The allocated length (in bytes) of the buffer containing the
login context.
buf[] An idl_byte array containing the importable login context.
Output
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and UUID,
account restrictions, records of group membership, and the
process home directory. (See sec_intro for more details about
the login context.)
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_import_context() routine imports a context obtained via
a call to sec_login_export_context() performed on the same machine. To
import a login context, users must have the appropriate privileges.
Nonprivileged users can import only their own login context; privileged
users can import the login contexts created by any users.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_context_invalid
The login context itself is not valid.
sec_login_s_default_use
Illegal use of the default login handle occurred.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_login_export_context
76 – sec_login_init_first
NAME
sec_login_init_first - Initializes the default context
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_init_first(
error_status_t *status);
PARAMETERS
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_init_first() routine initializes the default context
inheritance mechanism. If the default inheritance mechanism is already
initialized, the operation fails. Typically, this routine is called by
the initial process at machine boot time to initialize the default
context inheritance mechanism for the host machine process hierarchy.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_default_use
The default context is already initialized.
sec_login_s_privileged
An unprivileged process was called in.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_login_setup_first
sec_login_validate_first
77 – sec_login_inquire_net_info
NAME
sec_login_inquire_net_info - Returns a principal's network information
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_inquire_net_info(
sec_login_handle_t login_context,
sec_login_net_info_t *net_info,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to the login context for the desired principal.
(See sec_intro for more details about the login context.)
Output
net_info
A pointer to the returned sec_login_net_info_t data structure
that contains the principal's network information. The
sec_login_net_info_t structure is defined as follows:
typedef struct {
sec_id_pac_t pac;
unsigned32 acct_expiration_date;
unsigned32 passwd_expiration_date;
unsigned32 identity_expiration_date;
} sec_login_net_info_t;
};
status
A pointer to the completion status. On successful completion,
the routine returns one of the following status codes:
+ error_status_ok to indicate that the principal's network
information returned in the sec_login_net_info_t data
structure has been validated and certified.
+ sec_login_s_not_certified to indicate that the principal's
network information returned in the sec_login_net_info_t
data structure has been validated, but not certified.
Although this code indicates successful completion, it
warns you that the information is not validated.
If the call does not complete successfully, it returns an error.
DESCRIPTION
The sec_login_inquire_net_info() routine returns network information
for the principal identified by the specified login context. The
network information consists of the following:
+ The Privilege Attribute Certificate (PAC) that describes the
identity and group memberships of the principal.
+ The expiration date for the principal's account in the DCE
Registry.
+ The expiration date for the principal's password in the DCE
Registry.
+ The lifetime for the principal's authenticated network identity.
This is the lifetime of the principal's TGT (see the
sec_login_get_expiration() routine).
A value of 0 (zero) for an expiration date means there is no
expiration date. In other words, the principal's account, password,
or authenticated identity is good indefinitely.
To remove the returned net_info structure when it is no longer needed,
use sec_login_free_net_info().
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_not_certified
The login context is not certified.
sec_login_s_context_invalid
The login context is not valid.
sec_login_s_no_current_context
The default context was specified, but none exists.
sec_login_s_auth_local
Operation not valid on local context. The call's identity
was not authenticated.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_login_get_expiration
sec_login_free_net_info
78 – sec_login_newgroups
NAME
sec_login_newgroups - Changes the group list for a login context
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_newgroups(
sec_login_handle_t login_context,
sec_login_flags_t flags,
unsigned32 num_local_groups,
sec_id_t local_groups[],
sec_login_handle_t *restricted_context,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and
UUID, account restrictions, records of group membership, and
the process home directory. (See sec_intro for more details
about the login context.)
flags A set of flags of type sec_login_flags_t. These contain
information about how the new network credentials will be used.
Currently, the only flag used is sec_login_credentials_private,
that, when set, implies that the new context is only to be used
by the calling process. If this flag is not set (flags =
sec_login_no_flags), descendants of the calling process may
also use the new network credentials.
num_local_groups
An unsigned 32-bit integer containing the number of local group
identities to include in the new context.
local_groups[]
An array of sec_id_t elements. Each element contains the UUID
of a local group identity to include in the new context. These
identities are local to the cell. Optionally, each element may
also contain a pointer to a character string containing the
name of the local group.
Output
restricted_context
An opaque handle to the login context containing the changed
group list.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_newgroups() routine changes the group list for the
specified login context. Part of a network identity is a list of the
various groups to which a principal belongs. The groups are used to
determine a user's access to various objects and services. This
routine returns a new login context that contains the changed group
list. To remove the new login context when it is no longer needed,
use sec_login_purge_context().
This operation does not need to be validated as the user identity does
not change. Consequently, knowledge of the password is not needed.
NOTES
urrently you can have only groups from the local cell.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
RETURN VALUES
This routine returns TRUE when the new login context is successfully
established.
ERRORS
sec_login_s_auth_local
Operation not valid on local context.
sec_login_s_default_use
It is an error to try to certify the default context.
sec_login_s_groupset_invalid
The input list of group names is invalid. There may be
groups to which the caller does not belong, or the list
may contain groups that do not exist.
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the sec_login_newgroups()
routine as part of a process to change the groupset:
sec_login_get_current_context(&login_context, &st);
sec_login_get_groups(login_context, &num_groups, &groups, &st);
...the group IDs have to be converted from the returned UNIX
numbers into UUIDs (use sec_rgy_pgo_unix_num_to_id)...
for (i=0; i < num_groups; i++) {
... query whether the user wants to discard any of the
current group memberships. Copy new groupset to the new_groups
array ...
}
if ( !sec_login_newgroups(sec_login_no_flags, num_new_groups,
new_groups, &login_context, &st)) {
if (st == sec_login_s_groupset_invalid)
printf("New groupset invalid0);
... application specific error handling ...
}
RELATED INFORMATION
Functions: sec_intro
sec_login_get_groups
sec_login_purge_context
79 – sec_login_purge_context
NAME
sec_login_purge_context - Destroys a login context and frees its
storage
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_purge_context(
sec_login_handle_t *login_context,
error_status_t *status);
PARAMETERS
Input
login_context
A pointer to an opaque handle to login context data. The login
context contains, among other data, the account principal name
and UUID, account restrictions, records of group membership,
and the process home directory. (See sec_intro for more details
about the login context.) Note that a pointer to the handle is
submitted, so the handle may be reset to NULL upon successful
completion.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_purge_context() routine frees any storage allocated
for the specified login context and destroys the associated network
credentials, if any exist.
CAUTIONS
Applications must be cautious when purging the current context as
this destroys network credentials for all processes that share the
credentials.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_default_use
Illegal use of the default login handle occurred.
sec_login_s_context_invalid
The login context itself is not valid.
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the sec_login_purge_context()
routine as part of a straightforward login process:
if (sec_login_setup_identity( user_name,
sec_login_no_flags,
&login_context,
&st)) {
... get password from user...
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
if (!sec_login_certify_identity(login_context, &st))
exit(error_wierd_auth_svc);
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
if (reset_passwd) {
... get new password from user, reset registry record ...
};
sec_login_get_pwent(login_context, &pw_entry, &st);
if (pw_entry.pw_expire < todays_date) {
sec_login_purge_context(&login_context, &st);
exit(0)
}
... any other application specific login valid actions ...
}
} else {
sec_login_purge_context(&login_context, &st);
... application specific login failure actions ...
}
}
RELATED INFORMATION
Functions: sec_intro
sec_login_set_context
sec_login_setup_identity
sec_login_validate_identity
80 – sec_login_refresh_identity
NAME
sec_login_refresh_identity - Refreshes an authenticated identity for
a login context
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_refresh_identity(
sec_login_handle_t login_context,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and
UUID, account restrictions, records of group membership, and
the process home directory.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_refresh_identity() routine refreshes a previously
established identity. It operates on an existing valid context, and
cannot be used to change credentials associated with that identity.
The refreshed identity reflects changes that affect ticket lifetimes,
but not other changes. For example, the identity will reflect a change
to maximum ticket lifetime, but not the addition of the identity as a
member to a group. Only a DCE login reflects all administrative
changes made since the last login.
The refreshed identity must be validated with
sec_login_validate_identity() before it can be used.
It is an error to refresh a locally authenticated context.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_context_invalid
The login context itself is not valid.
sec_login_s_default_use
Illegal use of the default login handle occurred.
sec_login_s_no_memory
Not enough memory is available to complete the operation.
error_status_ok
The call was successful.
EXAMPLES
Since the authenticated network identity for a process has a finite
lifetime, there is a risk it will expire during some long network
operation, preventing the operation from completing.
For a server application that must run with an authenticated network
identity because they themselves sometimes act as clients of another
server, the sec_login calls can be used to check the network identity
expiration date, run sec_login_refresh_identity and
sec_login_validate_identity before the expiration. This will prevent
interruptions in the server's operation due to the restrictions in
network access applied to an unauthenticated identity.
sec_login_get_expiration(login_context, &expire_time, &st);
if (expire_time < (current_time + operation_duration)) {
if (!sec_login_refresh_identity(login_context, &st)) {
... login context cannot be renewed ...
... sleep and try again ....
}
} else {
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
... identity validated ...
} else {
... validation failed ...
exit(error_validation_failure);
}
}
}
operation();
RELATED INFORMATION
Functions: sec_intro
sec_login_validate_identity
81 – sec_login_release_context
NAME
sec_login_release_context - Frees storage allocated for a login
context
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_release_context(
sec_login_handle_t *login_context,
error_status_t *status);
PARAMETERS
Input/Output
login_context
A pointer to an opaque handle to login context data. The login
context contains, among other data, the account principal name
and UUID, account restrictions, records of group membership,
and the process home directory. (See sec_intro for more details
about the login context.)
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_release_context() routine frees any memory allocated
for a login context. Unlike sec_login_purge_context(), it does not
destroy the associated network credentials that still reside in the
credential cache.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_default_use
Illegal use of the default login handle occurred.
sec_login_s_context_invalid
The login context itself is invalid.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_login_purge_context
82 – sec_login_set_context
NAME
sec_login_set_context - Creates network credentials for a login
context
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_set_context(
sec_login_handle_t login_context,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and
UUID, account restrictions, records of group membership, and
the process home directory. (See sec_intro for more details
about the login context.)
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_set_context() routine sets the network credentials
to those specified by the login context. This context must have
been previously validated. Contexts acquired through
sec_login_get_current_context() or sec_login_newgroups() do not
need to be validated since those routines return previously
alidated contexts.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_context_invalid
The login context itself is invalid.
sec_login_s_default_use
Illegal use of the default login handle occurred.
sec_login_s_auth_local
Operation not valid on local context.
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the sec_login_set_context()
routine as part of a straightforward login process:
if (sec_login_setup_identity( user_name,
sec_login_no_flags,
&login_context,
&st )) {
... get password from user...
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
if (!sec_login_certify_identity(login_context, &st))
exit(error_weird_auth_svc);
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
if (reset_passwd) {
... get new password from user, reset registry record ...
};
sec_login_get_pwent(login_context, &pw_entry, &st);
if (pw_entry.pw_expire < todays_date) {
sec_login_purge_context(&login_context, &st);
exit(0)
}
... any other application specific login valid actions ...
}
} else {
sec_login_purge_context(&login_context, &st);
... application specific login failure actions ...
}
}
RELATED INFORMATION
Functions: sec_intro
sec_login_setup_identity
sec_login_validate_identity
83 – sec_login_set_extended_attrs
NAME
sec_login_set_extended_attrs - Constructs a new login context that
contains extended registry attributes
SYNOPSIS
#include <dce/sec_login.h>
sec_login_handle_t sec_login_set_extended_attrs(
sec_login_handle_t my_login_context,
unsigned32 num_attributes,
sec_attr_t attributes[]
error_status_t *status);
PARAMETERS
Input
my_login_context
A value of sec_login_handle_t that provides an opaque handle
to the identity of the calling client.
num_attributes
An unsigned 32-bit integer that specifies the number of elements
in the attributes[] array. The number must be greater than 0.
attributes[]
An array of values of type sec_attr_t that specifies the list of
attributes to be set in the new login context.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_set_extended_attrs() constructs a login context that
contains extended registry attributes that have been established for
the object identified by my_login_context. The attributes themselves
must have been established and attached to the object using the
Extended Registry Attribute API.
The input attributes[] array of sec_attr_t values should specify the
attr_id field for each requested attribute. Since the lookup is by
attribute type ID only, set the attribute.attr_value.attr_encoding
field to sec_attr_enc_void for each attribute. Note that sec_attr_t
is an Extended Registry Attribute data type. For more information on
Extended Registry Attributes, see the description of the sec_attr calls
in this document and the chapter titled "The Extended Registry
Attribute API" in the DCE Application Development Guide.
You cannot use this call to add extended registry attributes to a
delegation chain. If you pass in a login context that refers to a
delegation chain, an invalid context error will be returned.
The routine returns a new login context of type sec_login_handle_t
that includes the attributes specified in the attributes[] array.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_invalid_context
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_... calls
sec_login_become_impersonator
sec_login_setup_identity
sec_login_validate_identity
sec_login_set_context
84 – sec_login_setup_first
NAME
sec_login_setup_first - Sets up the default network context
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_setup_first(
sec_login_handle_t *init_context,
error_status_t *status);
PARAMETERS
Output
init_context
A pointer to an opaque handle to login context data. The login
context contains, among other data, the account principal name
and UUID, account restrictions, records of group membership,
and the process home directory. In this call, the context will
be that of the host machine initial process. (See sec_intro
for more details about the login context.)
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_setup_first() routine sets up the default context
network identity. If the default context already contains valid
credentials, the routine fails. Typically, this routine is called
from the Security Validation Service of the dced process to breathe
life into the default credentials for the host machine process
hierarchy.
This routine uses the hostname available via the local dce_config
interface as the principal name for the setup, so it does need a
principal name as input.
RETURN VALUES
The routine returns a boolean32 value that is TRUE if the setup was
successful, and FALSE otherwise.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_default_use
The default context is already in use and does not need
to be set up again.
sec_login_s_no_current_context
The calling process has no context of its own.
sec_login_s_privileged
An unprivileged process was called in.
sec_login_s_config
The DCE configuration (dce_config) information is not
available.
sec_rgy_object_not_found
The principal does not exist.
sec_rgy_server_unavailable
The network registry is not available.
sec_login_s_no_memory
A memory allocation error occurred.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_login_init_first
sec_login_validate_first
85 – sec_login_setup_identity
NAME
sec_login_setup_identity - Sets up the user's network identity
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_setup_identity(
unsigned_char_p_t principal,
sec_login_flags_t flags,
sec_login_handle_t *login_context,
error_status_t *status);
PARAMETERS
Input
principal
A pointer (type unsigned_char_p_t) indicating a character
string containing the principal name on the registry account
corresponding to the calling process.
flags A set of flags of type sec_login_flags_t. These contain
information about how the new network credentials are to be used.
Output
login_context
A pointer to an opaque handle to login context data. The login
context contains, among other data, the account principal name
and UUID, account restrictions, records of group membership,
and the process home directory. (See sec_intro for more details
about the login context.)
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_setup_identity() routine creates any local context
necessary to perform authenticated network operations. It does not
establish any local operating system context; that is the
responsibility of the caller. It is the standard network login
function. The network identity set up by this operation cannot be
used until it is validated via sec_login_validate_identity().
The sec_login_setup_identity() operation and the
sec_login_validate_identity() operation are two halves of a single
logical operation. Together they collect the identity data needed
to establish an authenticated identity.
NOTES
Neither sec_login_setup_identity() nor sec_login_validate_identity()
check for account or identity expiration. The application program
using this interface is responsible for such checks.
RETURN VALUES
The routine returns TRUE if the identity has been successfully
established.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_rgy_object_not_found
The principal does not exist.
sec_rgy_server_unavailable
The network registry is not available.
sec_login_s_no_memory
Not enough memory is available to complete the operation.
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the sec_login_setup_identity()
routine as part of a straightforward login process:
if (sec_login_setup_identity( user_name,
sec_login_no_flags,
&login_context,
&st )) {
... get password from user...
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
if (!sec_login_certify_identity(login_context, &st))
exit(error_weird_auth_svc);
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
if (reset_passwd) {
... get new password from user, reset registry record ...
};
sec_login_get_pwent(login_context, &pw_entry, &st);
if (pw_entry.pw_expire < todays_date) {
sec_login_purge_context(&login_context, &st);
exit(0)
}
... any other application specific login valid actions ...
}
} else {
sec_login_purge_context(&login_context, &st);
... application specific login failure actions ...
}
}
RELATED INFORMATION
Functions: sec_intro
sec_login_validate_identity
sec_login_set_context
86 – sec_login_valid_and_cert_ident
NAME
sec_login_valid_and_cert_ident - Validates and certifies a login
context
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_valid_and_cert_ident(
sec_login_handle_t login_context,
sec_passwd_rec_t *passwd,
boolean32 *reset_passwd,
sec_login_auth_src_t *auth_src,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and
UUID, account restrictions, records of group membership, and
the process home directory. (See sec_intro for more details
about the login context.)
passwd
A password record to be checked against the password in the
principal's registry account. The routine returns TRUE if the
two match. The contents of the passwd parameter are erased
after the call has finished processing it.
Output
reset_passwd
A pointer to a 32-bit boolean32 value. The routine returns
TRUE if the account password has expired and must be reset.
auth_src
A 32-bit set of flags identifying the source of the
authentication. Upon return after successful authentication,
the flags in auth_src indicate what authority was used to
validate the login context. If the authentication was
accomplished with the network authority, the
sec_login_auth_src_network flag is set, and the process login
context has credentials to use the network. If the
authentication was accomplished with local data only (either
the principal's account is tailored for the local machine
with overrides, or the network authority is unavailable), the
sec_login_auth_src_local flag is set. Login contexts that are
authenticated locally may not be used to establish network
credentials because they have none.
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_valid_and_cert_ident() routine validates and certifies
a login context established with sec_login_setup_identity(). The
caller must supply the user's password as input with the passwd
parameter.
This routine combines the operations of the
sec_login_validate_identity() and sec_login_certify_identity()
routines. It is intended for use by system login programs that
need to extract trustworthy operating system credentials for use
in setting the local identity for a process. This operation
destroys the contents of the passwd input parameter.
If the network security service is unavailable or if the user's
password has been overridden on the host, a locally authenticated
context is created, and the auth_src parameter is set to
sec_login_auth_src_local. Data extracted from a locally
authenticated context may be used to set the local OS identity, but
it cannot be used to establish network credentials.
This routine is a privileged operation.
RETURN VALUES
The routine returns TRUE if the login identity has been successfully
validated.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_rgy_passwd_invalid
The input string does not match the account password.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
sec_login_s_acct_invalid
The account is invalid or has expired.
sec_login_s_privileged
This is a privileged operation and was invoked by an
unprivileged process.
sec_login_s_null_password
The input string is NULL.
sec_login_s_default_use
The input context was the default context, which cannot be
validated.
sec_login_s_already_valid
The login context has already been validated.
sec_login_s_unsupp_passwd_type
The password type is not supported.
sec_login_s_no_memory
Not enough memory is available to complete the operation.
sec_login_s_preauth_failed
Preauthentication failure.
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the
sec_login_valid_and_cert_ident() routine as part of a system login
process:
if (sec_login_setup_identity(<user>,
sec_login_no_flags, &login_context, &st)) {
... get password ...
if (sec_login_valid_and_cert_ident(login_context,
password, &st)) {
if (auth_src == sec_login_auth_src_network) {
if (GOOD_STATUS(&st)
sec_login_set_context(login_context);
}
}
if (reset_passwd) {
... reset the user's password ...
if (passwd_reset_fails) {
sec_login_purge_context(login_context)
... application login failure actions ...
}
... application specific login valid actions ...
}
}
RELATED INFORMATION
Functions: sec_intro
sec_login_certify_identity
sec_login_setup_identity
sec_login_validate_identity
87 – sec_login_valid_from_keytable
NAME
sec_login_valid_from_keytable - Validates a login context's
identit using input from a
specified keytable file
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_valid_from_keytable(
sec_login_handle_t login_context,
unsigned32 authn_service,
void *arg,
unsigned32 try_kvno,
unsigned32 *used_kvno,
boolean32 *reset_passwd,
sec_login_auth_src_t *auth_src,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal's name and
UUID, account restrictions, records of the account principal's
group memberships, and the account's home directory. (See
sec_intro for more details about the login context.)
authn_service
Identifies the authentication protocol using the key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local keytab file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine.
A value of NULL specifies that the default keytab file should
be used. A keytab file name specifies that that file should be
used as the keytab file. You must prepend the file's absolute
filename with FILE: and the file must have been created with
the rgy_edit command or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the get_key_fn key
acquisition routine. See the rpc_server_register_auth_info()
reference page for more information.
try_kvno
The version number of the key in the keytab file to try first.
Specify NULL to try the current version of the key.
Output
used_kvno
A pointer to a 32-bit boolean32 value that specifies the
version number of the the key from the keytab file that was
used to successfully validate the login context, if any.
reset_passwd
A pointer to a 32-bit boolean32 value. The routine returns
TRUE if the account password has expired and should be reset.
auth_src
How the the login context was authorized. The
sec_login_auth_src_t data type distinguishes the various
ways the login context was authorized. There are three possible
values:
sec_login_auth_src_network
Authentication accomplished through the normal network
authority. A login context authenticated this way will
have all the network credentials it ought to have.
sec_login_auth_src_local
Authentication accomplished via local data.
Authentication occurs locally if a principal's
account is tailored for the local machine, or if
the network authority is unavailable. Since a login
contexts authenticated locally has no network
credentials, it can not be used for network
operations.
sec_login_auth_src_overridden
Authentication accomplished via the override facility.
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_valid_from_keytable () routine validates the login
context established with sec_login_setup_identity(). The
sec_login_valid_from_keytable () routine obtains the principal's
password from the specified keytable.
If try_kvno specifies a key version number, that version number key
is tried first, otherwise the current key version number is tried first.
The function trys all keys in the keytable until it finds one that
validates the login context. This operation must be invoked before the
network credentials can be used.
NOTES
A context is not secure and must not be set or exported until the
authentication service is itself authenticated with the
sec_login_certify_identity() call.
RETURN VALUES
The routine returns TRUE if the login context has been successfully
validated.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_rgy_passwd_invalid
The input string does not match the account password.
sec_rgy_server_unavailable
There is no data with which to compare the input string.
sec_login_s_acct_invalid
The account is invalid or has expired.
sec_login_s_default_use
The input context was the default context, which cannot
be validated.
sec_login_s_already_valid
The login context has already been validated.
sec_login_s_unsupp_passwd_type
The password type is not supported.
sec_key_mgmt_e_key_unavailable
The requested key is not present.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
sec_s_no_memory
Unable to allocate memory.
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the
sec_login_valid_from_keytable() routine as part of a straightforward
login process:
if (sec_login_setup_identity( user_name,
sec_login_no_flags,
&login_context,
&st )) {
... get password from local keytable...
if (sec_login_valid_from_keytable( login_context,
authn_service,
arg,
try_kvno,
&used_kvno,
&reset_passwd,
&auth_src,
&st )) {
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
}
... any other application specific login valid actions ...
}
} else {
sec_login_purge_context(&login_context, &st);
... application specific login failure actions ...
}
}
RELATED INFORMATION
Functions: sec_intro
sec_login_validate_identity
sec_login_certify_identity
sec_login_setup_identity
sec_login_valid_and_cert_ident
88 – sec_login_validate_first
NAME
sec_login_validate_first - Validates the initial login context
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_validate_first(
sec_login_handle_t init_context,
boolean32 *reset_passwd,
sec_login_auth_src_t *auth_src,
error_status_t *status);
PARAMETERS
Input
init_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and
UUID, account restrictions, records of group membership,
and the process home directory. In this call, the context
will be that of the host machine initial process. (See
sec_intro for more details about the login context.)
Output
reset_passwd
A pointer to a 32-bit boolean32 value. The routine returns
TRUE if the account password has expired and must be reset.
auth_src
A 32-bit set of flags identifying the source of the
authentication. Upon return after successful authentication,
the flags in auth_src indicate what authority was used to
validate the login context. If the authentication was
accomplished with the network authority, the
sec_login_auth_src_network flag is set, and the process login
context has credentials to use the network. If the
authentication was accomplished with local data only (either
the principal's account is tailored for the local machine with
overrides, or the network authority is unavailable), the
sec_login_auth_src_local flag is set. Login contexts that are
authenticated locally may not be used to establish network
credentials because they have none.
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_validate_first() routine validates the default login
context established via sec_login_setup_first(). Typically, this
operation is called from the Security Validation Service of the dced
process to validate the default credentials for the host machine
process hierarchy. This operation uses the password for the local
host, and therefore does not require a password parameter.
RETURN VALUES
The routine returns a boolean32 value that is TRUE if the setup was
successful, and FALSE otherwise.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_privileged
An unprivileged process was called in.
sec_rgy_server_unavailable
The network authentication service was unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_login_init_first
sec_login_setup_first
89 – sec_login_validate_identity
NAME
sec_login_validate_identity - Validates a login context's identity
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_validate_identity(
sec_login_handle_t login_context,
sec_passwd_rec_t *passwd,
boolean32 *reset_passwd,
sec_login_auth_src_t *auth_src,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and
UUID, account restrictions, records of group membership, and
the process home directory. (See sec_intro for more details
about the login context.)
passwd
A password record to be checked against the password in the
principal's registry account. The routine returns TRUE if the
two match. The contents of the passwd parameter are erased
after the call has finished processing it.
Output
reset_passwd
A pointer to a 32-bit boolean32 value. The routine returns
TRUE if the account password has expired and must be reset.
auth_src
How the the login context was authorized. The
sec_login_auth_src_t data type distinguishes the various
ways the login context was authorized. There are three
possible values:
sec_login_auth_src_network
sec_login_auth_src_local
sec_login_auth_src_overridden
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_validate_identity() routine validates the login context
established with sec_login_setup_identity(). This operation must be
invoked before the network credentials can be used. The caller must
supply the user's password in a sec_passwd_rec_t as input with the
passwd parameter. The following example sets up a plaintext password
for the passwd parameter:
sec_passwd_str_t tmp_passwd;
passwd.version_number = sec_passwd_c_version_none;
passwd.pepper = NULL;
passwd.key.key_type = sec_passwd_plain;
strncpy( (char *) tmp_passwd,
(char *) my_passwd,
sec_passwd_str_max_len );
tmp_passwd[sec_passwd_str_max_len] = ' ';
passwd_rec.key.tagged_union.plain = &(tmp_passwd[0]);
When a network identity is set, only state information for network
operations has been established. The local operating system identity
has not been modified. It is the responsibility of the caller to
establish any local operating identity state.
The sec_login_setup_identity() operation and the
sec_login_validate_identity() operation are two halves of a single
logical operation. Together they collect the identity data needed
to establish an authenticated identity. The operations are independent
so the user's password need not be sent across the network. The
identity validation performed by sec_login_validate_identity() is a
local operation.
NOTES
A context is not secure and must not be set or exported until the
authentication service is itself authenticated with the
sec_login_certify_identity() call.
System login programs that set local operating system identity
using data extracted from a login context should use
sec_login_valid_and_cert_ident() instead of
sec_login_validate_identity().
If the Security server and client clocks are not synchronized to
within 2 to 3 minutes of each other, this call can return a password
validation error.
RETURN VALUES
The routine returns TRUE if the login identity has been successfully
validated.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_rgy_passwd_invalid
The input string does not match the account password.
sec_rgy_server_unavailable
There is no data with which to compare the input string.
sec_login_s_acct_invalid
The account is invalid or has expired.
sec_login_s_null_password
The input string is NULL.
sec_login_s_default_use
The input context was the default context, which cannot
be validated.
sec_login_s_already_valid
The login context has already been validated.
sec_login_s_unsupp_passwd_type
The password type is not supported.
sec_login_s_no_memory
Not enough memory is available to complete the operation.
sec_login_s_preauth_failed
Preauthentication failure.
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the
sec_login_validate_identity() routine as part of a
straightforward login process:
if (sec_login_setup_identity( user_name,
sec_login_no_flags,
&login_context,
&st )) {
... get password from user...
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
if (!sec_login_certify_identity(login_context, &st))
exit(error_weird_auth_svc);
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
if (reset_passwd) {
... get new password from user, reset registry record ...
};
sec_login_get_pwent(login_context, &pw_entry, &st);
if (pw_entry.pw_expire < todays_date) {
sec_login_purge_context(&login_context, &st);
exit(0)
}
... any other application specific login valid actions ...
}
} else {
sec_login_purge_context(&login_context, &st);
... application specific login failure actions ...
}
}
RELATED INFORMATION
Functions: sec_intro
sec_login_certify_identity
sec_login_setup_identity
sec_login_valid_and_cert_ident
90 – sec_pwd_mgmt_free_handle
NAME
sec_pwd_mgmt_free_handle - Frees storage allocated for a
password management handle
SYNOPSIS
#include <dce/sec_pwd_mgmt.h>
void sec_pwd_mgmt_free_handle(
sec_pwd_mgmt_handle_t *pwd_mgmt_h,
error_status_t *stp
)
PARAMETERS
Input/Output
pwd_mgmt_h
A handle to the password management data which is to be freed.
Output
stp A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_pwd_mgmt_free_handle() routine frees any memory allocated for
the contents of a password management handle.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_PWD_MGMT.IDL
The idl file from which dce/sec_pwd_mgmt.h was derived.
ERRORS
error_status_ok
The call was successful
RELATED INFORMATION
Functions: sec_intro
sec_pwd_mgmt_setup
91 – sec_pwd_mgmt_gen_pwd
NAME
sec_pwd_mgmt_gen_pwd - Generate a set of passwords
SYNOPSIS
#include <dce/sec_pwd_mgmt.h>
void sec_pwd_mgmt_gen_pwd(
sec_pwd_mgmt_handle_t pwd_mgmt_h,
unsigned32 num_pwds,
unsigned32 *num_returned,
sec_passwd_rec_t gen_pwds[],
error_status_t *stp
)
PARAMETERS
Input
pwd_mgmt_h
A handle to user's password management data.
num_pwds
Number of generated passwords requested.
Output
num_returned
Number of generated passwords returned in the gen_pwds[] array.
gen_pwds
Array of generated passwords. Each generated password is stored
in a sec_passwd_rec_t structure.
stp A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_pwd_mgmt_gen_pwd() routine retrieves a set of generated
passwords from a password management server which is exporting the
rsec_pwd_mgmt_gen_pwd() routine. It obtains the binding information
to this server from the pwd_mgmt_h handle.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_PWD_MGMT.IDL
The idl file from which dce/sec_pwd_mgmt.h was derived.
ERRORS
sec_rgy_era_pwd_mgmt_auth_type
The pwd_mgmt_binding ERA must contain authentication
information.
sec_pwd_mgmt_svr_unavail
The password management server is unavailable
sec_pwd_mgmt_svr_error
Generic error returned from password management server.
An administrator should check the password management
server's log file for more information.
error_status_ok
The call was successful
Various RPC communication errors can be returned if there are failures
when binding to the password management server.
RELATED INFORMATION
Functions: sec_intro
sec_pwd_mgmt_setup
pwd_strengthd
92 – sec_pwd_mgmt_get_val_type
NAME
sec_pwd_mgmt_get_val_type - Gets users password validation type
SYNOPSIS
#include <dce/sec_pwd_mgmt.h>
void sec_pwd_mgmt_get_val_type(
sec_pwd_mgmt_handle_t pwd_mgmt_h,
signed32 *pwd_val_type,
error_status_t *stp
)
PARAMETERS
Input
pwd_mgmt_h
A handle to a user's password management data.
Output
pwd_val_type
The user's password validation type. This is retrieved from the
pwd_val_type ERA. The possible values and their meaning are:
(none): the user has no password policy.
(user_select): the user must choose his/her own password.
(user_can_select): the user can choose his/her own password
or request a generated password.
(generation_required): the user must use a generated password.
stp A pointer to the completion status. On successful completion,
stp is assigned error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_pwd_mgmt_get_val_type() routine returns the value of the
user's password validation type, as specified by the pwd_val_type ERA.
If the ERA does not exist, 0 (none) is returned in pwd_val_type.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_PWD_MGMT.IDL
The idl file from which dce/sec_pwd_mgmt.h was derived.
ERRORS
error_status_ok
The call was successful
Various RPC communication errors can be returned if there are failures
when binding to the password management server.
RELATED INFORMATION
Functions: sec_intro
sec_pwd_mgmt_setup
93 – sec_pwd_mgmt_setup
NAME
sec_pwd_mgmt_setup - Sets up the user's password policy information
SYNOPSIS
#include <dce/sec_pwd_mgmt.h>
void sec_pwd_mgmt_setup(
sec_pwd_mgmt_handle_t *pwd_mgmt_h,
sec_rgy_handle_t context,
sec_rgy_login_name_t login_name,
sec_login_handle_t your_lc,
rpc_binding_handle_t pwd_mgmt_bind_h,
error_status_t *stp
)
PARAMETERS
Input
context
A registry server handle indicating the desired registry site.
login_name
The login name of the user.
your_lc
The login context handle of the user currently logged in. If
null is specified, the default login context will be used.
pwd_mgmt_bind_h
An RPC binding handle to the password management server. Use of
this parameter is currently unsupported. The password management
server binding handle will be retrieved from the pwd_mgmt_binding
ERA. Set this parameter to NULL.
Output
pwd_mgmt_h
A pointer to an opaque handle to password management/policy data.
pwd_mgmt_h contains, among other data, the account name, values
of password management ERAs, and a binding handle to the password
management server.
stp A pointer to the completion status. On successful completion,
stp is assigned error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_pwd_mgmt_setup() routine collects the data required to perform
remote password management calls to the password management server.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_PWD_MGMT.IDL
The idl file from which dce/sec_pwd_mgmt.h was derived.
ERRORS
sec_s_no_memory
Not enough memory is available to complete the operation.
sec_rgy_server_unavailable
The network registry is not available.
error_status_ok
The call was successful
RELATED INFORMATION
Functions: sec_intro
sec_pwd_mgmt_free_handle
sec_pwd_mgmt_gen_pwd
sec_pwd_mgmt_get_val_type
pwd_strengthd
94 – sec_rgy_acct_add
NAME
sec_rgy_acct_add - Adds an account for a login name
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_add(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_key_t *key_parts,
sec_rgy_acct_user_t *user_part,
sec_rgy_acct_admin_t *admin_part,
sec_passwd_rec_t *caller_key,
sec_passwd_rec_t *new_key,
sec_passwd_type_t new_keytype,
sec_passwd_version_t *new_key_version,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
login_name
A pointer to the account login name. A login name is composed
of three character strings, containing the principal, group,
and organization (PGO) names corresponding to the account.
All three names must be completely specified.
key_parts
A pointer to the minimum abbreviation allowed when logging in
to the account. Abbreviations are not currently implemented and
the only legal value is sec_rgy_acct_key_person.
user_part
A pointer to the sec_rgy_acct_user_t structure containing the
user part of the account data. This represents such information
as the account password, home directory, and default shell.
admin_part
A pointer to the sec_rgy_acct_admin_t structure containing the
administrative part of an account's data. This information
includes the account creation and expiration dates and flags
describing limits to the use of privilege attribute certificates,
among other information.
caller_key
A key to use to encrypt new_key for transmission to the registry
server.
new_key
The password for the new account. During transmission to the
registry server, it is encrypted with caller_key.
new_keytype
The type of the new key. The server uses this parameter to decide
how to encode new_key if it is sent as plaintext.
Output
new_key_version
The key version number returned by the server. If the client
requests a particular key version number (via the version_number
field of the new_key input parameter), the server returns the
requested version number back to the client.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_add() routine adds an account with the specified
login name. The login name is given in three parts, corresponding to
the principal, group, and organization names for the account.
The key_parts variable specifies the minimum login abbreviation for
the account. If the requested abbreviation duplicates an existing
abbreviation for another account, the routine supplies the next
shortest unique abbreviation and returns this abbreviation in
key_parts. Abbreviations are not currently implemented.
Permissions Required
The sec_rgy_acct_add() routine requires the following permissions on the
account (principal) that is to be added:
+ The m (mgmt_info) permission to change management information.
+ The a (auth_info) permission to change authentication information.
+ The u (user_info) permission to change user information.
NOTES
The constituent principal, group, and organization (PGO) items for
an account must be added before the account can be created. (See the
sec_rgy_pgo_add() routine). Also, the principal must have been added
as a member of the specified group and organization. (See the
sec_rgy_pgo_add_member() routine).
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to add an account
to the registry.
sec_rgy_not_member_group
The indicated principal is not a member of the indicated
group.
sec_rgy_not_member_org
The indicated principal is not a member of the indicated
organization.
sec_rgy_not_member_group_org
The indicated principal is not a member of the indicated
group or organization.
sec_rgy_object exists
The account to be added already exists.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_delete
sec_rgy_login_get_info
sec_rgy_pgo_add
sec_rgy_pgo_add_member
sec_rgy_site_open
95 – sec_rgy_acct_admin_replace
NAME
sec_rgy_acct_admin_replace - Replaces administrative account data
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_admin_replace(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_key_t *key_parts,
sec_rgy_acct_admin_t *admin_part,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
login_name
A pointer to the account login name. A login name is composed
of three character strings, containing the principal, group,
and organization (PGO) names corresponding to the account.
For the group and organization names, blank strings can serve
as wildcards, matching any entry. The principal name must be
input.
key_parts
A pointer to the minimum abbreviation allowed when logging in
to the account. Abbreviations are not currently implemented
and the only legal value is sec_rgy_acct_key_person.
admin_part
A pointer to the sec_rgy_acct_admin_t structure containing the
administrative part of an account's data. This information
includes the account creation and expiration dates and flags
describing limits to the use of privilege attribute
certificates, among other information, and can be modified
only by an administrator. The sec_rgy_acct_admin_t structure
contains the following fields:
creator
The identity of the principal who created this account
in sec_rgy_foreign_id_t form. This field is set by the
registry server.
creation_date
The date (sec_timeval_sec_t) the account was created.
This field is set by the registry server.
last_changer
The identity of the principal who last modified any of
the account information (user or administrative). This
field is set by the registry server.
change_date
The date (sec_timeval_sec_t) the account was last
modified (either user or administrative data). This
field is set by the registry server.
expiration_date
The date (sec_timeval_sec_t) the account will cease
to be valid.
good_since_date
This date (sec_timeval_sec_t) is for Kerberos-style,
ticket-granting ticket revocation. Ticket-granting
tickets issued before this date will not be honored
by authenticated network services.
flags Contains administration flags used as part of the
administrator's information for any registry account.
This field is in sec_rgy_acct_admin_flags_t form.
(See sec_intro for a complete description of these
flags.)
authentication_flags
Contains flags controlling use of authentication
services. This field is in sec_rgy_acct_auth_flags_t
form. (See sec_intro for a complete description of
these flags.)
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_admin_replace() routine replaces the administrative
information in the account record specified by the input login name.
The administrative information contains limitations on the account's
use and privileges. It can be modified only by a registry
administrator; that is, a user with the admin_info (abbreviated as a)
privilege for an account.
The key_parts variable identifies how many of the login_name parts to
use as the unique abbreviation for the account. If the requested
abbreviation duplicates an existing abbreviation for another account,
the routine supplies the next shortest unique abbreviation and returns
this abbreviation using key_parts.
Permissions Required
The sec_rgy_acct_admin_replace() routine requires the following
permissions on the account principal:
+ The m (mgmt_info) permission, if flags or expiration_date is to be
changed.
+ The a (auth_info) permission, if authentication_flags or
good_since_date is to be changed.
NOTES
All users need the w (write) privilege in the appropriate ACL entry to
modify any account information.
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to change the
administrative information for the specified account.
sec_rgy_object_not_found
The registry server could not find the specified name.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_user_replace
sec_rgy_acct_replace_all
sec_rgy_acct_lookup
96 – sec_rgy_acct_delete
NAME
sec_rgy_acct_delete - Deletes an account
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_delete(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
error_status_t *status);
PARAMETERS
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
login_name
A pointer to the account login name. A login name is composed
of three character strings, containing the principal, group,
and organization (PGO) names corresponding to the account.
Only the principal name is required to perform the deletion.
Output
status A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_delete() routine deletes from the registry the account
corresponding to the specified login name.
Permissions Required
The sec_rgy_acct_delete() routine requires the following permissions
on the account principal:
+ The m (mgmt_info) permission to remove management information.
+ The a (auth_info) permission to remove authentication information.
+ The u (user_info) permission to remove user information.
NOTES
Even though the account is deleted, the PGO items corresponding to the
account remain. These must be deleted with separate calls to
sec_rgy_pgo_delete().
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to delete the
specified account.
sec_rgy_object_not_found
No PGO item was found with the given name.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_add
sec_rgy_pgo_delete
97 – sec_rgy_acct_get_projlist
NAME
sec_rgy_acct_get_projlist - Returns the projects in an account's
project list
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_get_projlist(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_cursor_t *projlist_cursor,
signed32 max_number,
signed32 *supplied_number,
uuid_t id_projlist[],
signed32 unix_projlist[],
signed32 *num_projects,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
login_name
A pointer to the account login name. A login name is composed
of three character strings, containing the principal, group, and
organization (PGO) names corresponding to the account. For the
group and organization names, blank strings can serve as
wildcards, matching any entry. The principal name must be input.
max_number
The maximum number of projects to be returned by the call. This
must be no larger than the allocated size of the projlist[]
arrays.
Input/Output
projlist_cursor
An opaque pointer indicating a specific project in an account's
project list. The sec_rgy_acct_get_projlist() routine returns the
project indicated by projlist_cursor, and advances the cursor to
point to the next project in the list. When the end of the list
is reached, the routine returns the value sec_rgy_no_more_entries
in the status parameter. Use sec_rgy_cursor_reset() to reset the
cursor.
Output
supplied_number
A pointer to the actual number of projects returned. This will
always be less than or equal to the max_number supplied on input.
If there are more projects in the account list,
sec_rgy_acct_get_projlist() sets projlist_cursor to point to the
next entry after the last one in the returned list.
id_projlist[]
An array to receive the UUID of each project returned. The size
allocated for the array is given by max_number. If this value
is less than the total number of projects in the account project
list, multiple calls must be made to return all of the projects.
unix_projlist[]
An array to receive the UNIX number of each project returned.
The size allocated for the array is given by max_number. If
this value is less than the total number of projects in the
account project list, multiple calls must be made to return all
of the projects.
num_projects
A pointer indicating the total number of projects in the
specified account's project list.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_get_projlist() routine returns members of the project
list for the specified account. It returns the project information in
two arrays. The id_projlist[] array contains the UUIDs for the returned
projects. The unix_projlist[] array contains the UNIX numbers for the
returned projects.
The project list cursor, projlist_cursor, provides an automatic place
holder in the project list. The sec_rgy_acct_get_projlist() routine
automatically updates this variable to point to the next project in the
project list. To return an entire project list, reset projlist_cursor
with sec_rgy_cursor_reset() on the initial call and then issue
successive calls until all the projects are returned.
Permissions Required
The sec_rgy_acct_get_projlist() routine requires the r (read)
permission on the account principal for which the project list data
is to be returned.
CAUTIONS
There are several different types of cursors used in the registry
Application Programmer Interface (API). Some cursors point to PGO
items, others point to members in a membership list, and others point
to account data. Do not use a cursor for one sort of object in a call
expecting another sort of object. For example, you cannot use the same
cursor on a call to sec_rgy_acct_get_projlist() and
sec_rgy_pgo_get_next(). The behavior in this case is undefined.
Furthermore, cursors are specific to a server. A cursor pointing into
one replica of the registry database is useless as a pointer into
another replica.
Use sec_rgy_cursor_reset() to refresh a cursor for use with another call
or for another server.
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_no_more_entries
The cursor is at the end of the list of projects.
sec_rgy_not_authorized
The client program is not authorized to see a project list
for this principal.
sec_rgy_object exists
The account to be added already exists.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_cursor_reset
sec_rgy_pgo_get_next
98 – sec_rgy_acct_lookup
NAME
sec_rgy_acct_lookup - Returns data for a specified account
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_lookup(
sec_rgy_handle_t context,
sec_rgy_login_name_t *name_key,
sec_rgy_cursor_t *account_cursor,
sec_rgy_login_name_t *name_result,
sec_rgy_sid_t *id_sid,
sec_rgy_unix_sid_t *unix_sid,
sec_rgy_acct_key_t *key_parts,
sec_rgy_acct_user_t *user_part,
sec_rgy_acct_admin_t *admin_part,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_key
A pointer to the account login name. A login name is composed
of three character strings, containing the principal, group,
and organization (PGO) names corresponding to the account.
Blank strings serve as wildcards, matching any entry.
Input/Output
account_cursor
An opaque pointer to a specific account in the registry database.
If name_key is blank, sec_rgy_acct_lookup() returns information
about the account to which the cursor is pointing. On return,
the cursor points to the next account in the database after the
returned account. If name_key is blank and the account_cursor
has been reset with sec_rgy_cursor_reset(),
sec_rgy_acct_lookup() returns information about the first
account in the database. When the end of the list of accounts
in the database is reached, the routine returns the value
sec_rgy_no_more_entries in the status parameter. Use
sec_rgy_cursor_reset() to refresh the cursor.
Output
name_result
A pointer to the full login name of the account (including all
three names) for which the information is returned. The
remaining parameters contain the information belonging to the
returned account.
id_sid
A structure containing the three UUIDs of the principal, group,
and organization for the account.
unix_sid
A structure containing the three UNIX numbers of the principal,
group, and organization for the account.
key_parts
A pointer to the minimum abbreviation allowed when logging in
to the account. Abbreviations are not currently implemented
and the only legal value is sec_rgy_acct_key_person.
user_part
A pointer to the sec_rgy_acct_user_t structure containing the
user part of the account data. This represents such information
as the account password, home directory, and default shell, all
of which are accessible to, and may be modified by, the account
owner.
admin_part
A pointer to the sec_rgy_acct_admin_t structure containing the
administrative part of an account's data. This information
includes the account creation and expiration dates and flags
describing limits to the use of privilege attribute
certificates, among other information, and can be modified
only by an administrator.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_lookup() routine returns all the information about
an account in the registry database. The account can be specified
either with name_key or account_cursor. If name_key is completely
blank, the routine uses the account_cursor value instead.
For name_key, a zero-length principal, group, or organization key
serves as a wildcard. For example, a login name key with the
principal and organization fields blank returns the next (possibly
first) account whose group matches the input group field. The full
login name of the returned account is passed back in name_result.
The account_cursor provides an automatic place holder in the registry
database. The routine automatically updates this variable to point to
the next account in the database, after the account for which the
information was returned. If name_key is blank and the account_cursor
has been reset with sec_rgy_cursor_reset()*O, sec_rgy_acct_lookup()
returns information about the first account in the database.
Permissions Required
The sec_rgy_acct_lookup() routine requires the r (read) permission
on the account principal to be viewed.
CAUTIONS
There are several different types of cursors used in the registry
Application Programmer Interface (API). Some cursors point to PGO
items, others point to members in a membership list, and others point
to account data. Do not use a cursor for one sort of object in a call
expecting another sort of object. For example, you cannot use the
same cursor on a call to sec_rgy_acct_get_projlist() and
sec_rgy_pgo_get_next(). The behavior in this case is undefined.
Furthermore, cursors are specific to a server. A cursor pointing into
one replica of the registry database is useless as a pointer into
another replica.
Use sec_rgy_cursor_reset() to renew a cursor for use with another call
or for another server.
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_no_more_entries
The cursor is at the end of the accounts in the registry.
sec_rgy_object_not_found
The input account could not be found by the registry
server.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_cursor_reset
sec_rgy_acct_replace_all
sec_rgy_acct_admin_replace
sec_rgy_acct_user_replace
99 – sec_rgy_acct_passwd
NAME
sec_rgy_acct_passwd - Changes the password for an account
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_passwd(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_passwd_rec_t *caller_key,
sec_passwd_rec_t *new_key,
sec_passwd_type_t new_keytype,
sec_passwd_version_t *new_key_version,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
login_name
A pointer to the account login name. A login name is composed
of three character strings, containing the principal, group,
and organization (PGO) names corresponding to the account.
All three strings must be completely specified.
caller_key
A key to use to encrypt the key for transmission to the registry
server. If communications secure to the
rpc_c_authn_level_pkt_privacy level are available on a system,
then this parameter is not necessary, and the packet encryption
is sufficient to ensure security.
new_key
The password for the new account. During transmission to the
registry server, it is encrypted with caller_key.
new_keytype
The type of the new key. The server uses this parameter to decide
how to encode new_key if it is sent as plaintext.
Output
new_key_version
The key version number returned by the server. If the client
requests a particular key version number (via the version_number
field of the new_key input parameter), the server returns the
requested version number back to the client.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_passwd() routine changes an account password to the
input password character string. Wildcards (blank fields) are not
permitted in the specified account name; the principal, group, and
organization names of the account must be completely specified.
Permissions Required
The sec_rgy_acct_passwd() routine requires the u (user_info)
permission on the account principal whose password is to be changed.
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to change the
password of this account.
sec_rgy_object_not_found
The account to be modified was not found by the registry
server.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
100 – sec_rgy_acct_rename
NAME
sec_rgy_acct_rename - Changes an account login name
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_rename(
sec_rgy_handle_t context,
sec_rgy_login_name_t *old_login_name,
sec_rgy_login_name_t *new_login_name,
sec_rgy_acct_key_t *new_key_parts,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
old_login_name
A pointer to the current account login name. The login name is
composed of three character strings, containing the principal,
group, and organization (PGO) names corresponding to the
account. All three strings must be completely specified.
new_login_name
A pointer to the new account login name. Again, all three
component names must be completely specified.
Input/Output
new_key_parts
A pointer to the minimum abbreviation allowed when logging in
to the account. Abbreviations are not currently implemented and
the only legal value is sec_rgy_acct_key_person.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_rename() routine changes an account login name from
old_login_name to new_login_name. Wildcards (empty fields) are not
permitted in either input name; both the old and new login names must
completely specify their component principal, group, and organization
names. Note, though, that the principal component in a login name
cannot be changed.
The new_key_parts variable identifies how many of the new_login_name
parts to use as the unique abbreviation for the account. If the
requested abbreviation duplicates an existing abbreviation for another
account, the routine identifies the next shortest unique abbreviation
and returns this abbreviation using new_key_parts.
Permissions Required
The sec_rgy_acct_rename() routine requires the m (mgmt_info)
permission on the account principal to be renamed.
NOTES
The sec_rgy_acct_rename() routine does not affect any of the registry
PGO data. The constituent principal, group, and organization items
for an account must be added before the account can be created.
(See the sec_rgy_pgo_add routine). Also, the principal must have
been added as a member of the specified group and organization.
(See the sec_rgy_pgo_add_member routine).
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to make the changes.
sec_rgy_object_not_found
The account to be modified was not found by the registry
server.
sec_rgy_name_exists
The new account name is already in use by another account.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_add
101 – sec_rgy_acct_replace_all
NAME
sec_rgy_acct_replace_all - Replaces all account data for an account
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_replace_all(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_key_t *key_parts,
sec_rgy_acct_user_t *user_part,
sec_rgy_acct_admin_t *admin_part,
boolean32 set_password,
sec_passwd_rec_t *caller_key,
sec_passwd_rec_t *new_key,
sec_passwd_type_t new_keytype,
sec_passwd_version_t *new_key_version,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
login_name
A pointer to the account login name. A login name is composed
of three character strings, containing the principal, group,
and organization (PGO) names corresponding to the account. For
the group and organization names, blank strings can serve as
wildcards, matching any entry. The principal name must be input.
user_part
A pointer to the sec_rgy_acct_user_t structure containing the
user part of the account data. This represents such information
as the account password, home directory, and default shell, all
of which are accessible to, and may be modified by, the account
owner.
admin_part
A pointer to the sec_rgy_acct_admin_t structure containing the
administrative part of an account's data. This information
includes the account creation and expiration dates and flags
describing limits to the use of privilege attribute
certificates, among other information, and can be modified only
by an administrator.
set_passwd
The password reset flag. If you set this parameter to TRUE, the
account's password will be changed to the value specified in
new_key.
caller_key
A key to use to encrypt the key for transmission to the registry
server. If communications secure to the
rpc_c_authn_level_pkt_privacy level are available on a system,
then this parameter is not necessary, and the packet encryption
is sufficient to ensure security.
new_key
The password for the new account. During transmission to the
registry server, it is encrypted with caller_key.
new_keytype
The type of the new key. The server uses this parameter to
decide how to encode the plaintext key.
Input/Output
key_parts
A pointer to the minimum abbreviation allowed when logging in
to the account. Abbreviations are not currently implemented
and the only legal value is sec_rgy_acct_key_person.
Output
new_key_version
The key version number returned by the server. If the client
requests a particular key version number (via the version_number
field of the new_key input parameter), the server returns the
requested version number back to the client.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_replace_all() routine replaces both the user and
administrative information in the account record specified by the
input login name. The administrative information contains limitations
on the account's use and privileges. The user information contains
such information as the account home directory and default shell.
Typically, the administrative information can only be modified by a
registry administrator (users with admin_info (a) privileges for an
account), while the user information can be modified by the account
owner (users with user_info (u) privileges for an account).
Use the set_passwd parameter to reset the account password. If you set
this parameter to TRUE, the account's pasword is changed to the value
specified in new_key.
The key_parts variable identifies how many of the login_name parts to
use as the unique abbreviation for the replaced account. If the
requested abbreviation duplicates an existing abbreviation for another
account, the routine identifies the next shortest unique abbreviation
and returns this abbreviation using key_parts.
Permissions Required
The sec_rgy_acct_replace_all() routine requires the following
permissions on the account principal:
+ The m (mgmt_info) permission, if flags or expiration_date is to
be changed.
+ The a (auth_info) permission, if authentication_flags or
good_since_date is to be changed.
+ The u (user_info) permission, if user flags, gecos, homedir (home
directory), shell, or passwd (password) are to be changed.
NOTES
All users need the w (write) privilege to modify any account
information.
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to change account
information.
sec_rgy_object_not_found
The specified account could not be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_add
sec_rgy_acct_admin_replace
sec_rgy_acct_rename
sec_rgy_acct_user_replace
102 – sec_rgy_acct_user_replace
NAME
sec_rgy_acct_user_replace - Replaces user account data
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_user_replace(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_user_t *user_part,
boolean32 set_passwd,
sec_passwd_rec_t *caller_key,
sec_passwd_rec_t *new_key,
sec_passwd_type_t new_keytype,
sec_passwd_version_t *new_key_version,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
login_name
A pointer to the account login name. A login name is composed
of three character strings, containing the principal, group,
and organization (PGO) names corresponding to the account.
For the group and organization names, blank strings can serve
as wildcards, matching any entry. The principal name must be
input.
user_part
A pointer to the sec_rgy_acct_user_t structure containing the
user part of the account data. This represents such information
as the account password, home directory, and default shell, all
of which are accessible to, and may be modified by, the account
owner. The structure contains the following fields:
gecos
A character string containing information about the
account owner. This often includes such information as
their name and telephone number.
homedir
The default directory upon login for the account.
shell The default shell to use upon login.
passwd_version_number
The password version number, a 32-bit unsigned integer,
set by the registry server.
passwd_dtm
The date and time of the last password change (in
sec_timeval_sec_t form), also set by the registry server.
flags A flag set of type sec_rgy_acct_user_flags_t.
passwd
The account's encrypted password.
set_passwd
The password reset flag. If you set this parameter to TRUE,
the user's password will be changed to the value specified
in new_key.
caller_key
A key to use to encrypt the key for transmission to the
registry server. If communications secure to the
rpc_c_authn_level_pkt_privacy level are available on a system,
then this parameter is not necessary, and the packet
encryption is sufficient to ensure security.
new_key
The password for the new account. During transmission to the
registry server, it is encrypted with caller_key.
new_keytype
The type of the new key. The server uses this parameter to
decide how to encode the plaintext key.
Output
new_key_version
The key version number returned by the server. If the client
requests a particular key version number (via the version_number
field of the new_key input parameter), the server returns the
requested version number back to the client.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_user_replace() routine replaces the user information
in the account record specified by the input login name. The user
information contains such information as the account home directory
and default shell. Typically, the the user information can be
modified by the account owner (users with user_info (u) privileges
for an account).
Use the set_passwd parameter to reset the user's password. If you set
this parameter to TRUE, the user's pasword is changed to the value
specified in new_key.
Permissions Required
The sec_rgy_acct_user_replace() routine requires the u (user_info)
permission on the account principal.
NOTES
All users need the w (write) privilege to modify any account
information.
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to modify the
account data.
sec_rgy_object_not_found
The specified account could not be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_add
sec_rgy_acct_admin_replace
sec_rgy_acct_rename
sec_rgy_acct_replace_all
103 – sec_rgy_attr_cursor_alloc
NAME
sec_rgy_attr_cursor_alloc - Allocates resources to a cursor used by
the sec_rgy_attr_lookup_by_id call
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_cursor_alloc(
sec_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Output
cursor A pointer to a sec_attr_cursor_t.
status
A pointer to the completion status. On successful completion,
the call returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_cursor_alloc() call allocates resources to a cursor
used with the sec_rgy_attr_lookup_by_id call. This routine, which is
a local operation, does not initialize cursor.
The sec_rgy_attr_cursor_init() routine, which makes a remote call,
allocates and initializes the cursor. In addition,
sec_rgy_attr_cursor_init() returns the total number of attributes
attached to the object as an output parameter;
sec_rgy_attr_cursor_alloc() does not.
Permissions Required
None
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_ATTR_BASE.IDL
The idl file from which dce/sec_attr_base.h was derived.
ERRORS
no such object
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_cursor_init
sec_rgy_attr_cursor_release
sec_rgy_attr_cursor_reset
sec_rgy_attr_lookup_by_id
104 – sec_rgy_attr_cursor_init
NAME
sec_rgy_attr_cursor_init - Initialize a cursor used by the
sec_rgy_attr_lookup_by_id call
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_cursor_init (
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
unsigned32 *cur_num_attrs,
sec_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
A value of type sec_rgy_domain_t that identifies the registry
domain in which the object specified by name resides. The valid
values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
This parameter is ignored if name is policy or replist.
name A pointer to a sec_rgy_name_t character string containing the
name of the person, group, or organization to which the
attribute to be scanned is attached.
Output
cur_num_attrs
A pointer to an unsigned 32-bit integer that specifies the
number of attributes currently attached to the object.
cursor
A pointer to a sec_rgy_cursor_t positioned at the first
attribute in the list of the object's attributes.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_cursor_init() routine initializes a cursor of type
sec_attr_cursor_t (used with the sec_rgy_attr_lookup_by_id call) and
initializes the cursor to the first attribute in the specified object's
list of attributes. This call also supplies the total number of
attributes attached to the object as part of its output. The cursor
allocation is a local operation. The cursor initialization is a remote
operation and makes a remote call to the Registry.
Use the sec_rgy_attr_cursor_release() call to release all resources
allocated to a sec_attr_cursor_t cursor.
Permissions Required
The sec_rgy_attr_cursor_init() routine requires at least one permission
(of any type) on the person, group, or organization to which the
attribute to be scanned is attached.
ERRORS
no such object
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_lookup_by_id
sec_rgy_attr_cursor_release
105 – sec_rgy_attr_cursor_release
NAME
sec_rgy_attr_cursor_release - Release a cursor of
typesec_attr_cursor_t that was
allocated with the
sec_rgy_attr_cursor_init() or
sec_rgy_attr_cursor_alloc() call
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_cursor_release (
sec_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
Input/Output
*cursor
As an input parameter, a pointer to an uninitialized cursor of
type sec_attr_cursor_t. As an output parameter, a pointer to an
uninitialized cursor of type sec_attr_cursor_t with all resources
released.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_cursor_release() routine releases all resources
allocated to a sec_attr_cursor_t by the sec_rgy_attr_cursor_init()
or sec_rgy_attr_cursor_alloc() call.
This is a local-only operation and makes not remote calls.
Permissions Required
None.
ERRORS
No such object
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_cursor_init
sec_rgy_attr_cursor_alloc
sec_rgy_attr_lookup_by_id
106 – sec_rgy_attr_cursor_reset
NAME
sec_rgy_attr_cursor_reset - Rinitializes a cursor that has
been allocated with either
sec_rgy_attr_cursor_init() or
sec_rgy_attr_cursor_alloc().
SYNOPSIS
#include <dce/sec_attr_base.h>
void sec_attr_cursor_reset(
sec_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input/Output
cursor
A pointer to a sec_attr_cursor_t. As an input parameter, an
initialized cursor. As an output parameter, cursor is reset to
the first attribute in the schema.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_cursor_reset() routine resets a dce_attr_cursor_t
that has been allocated by either a sec_rgy_attr_cursor_init() or
sec_rgy_attr_cursor_alloc(). The reset cursor can then be used to
process a new sec_rgy_attr_lookup_by_id query by reusing the cursor
instead of releasing and re-allocating it. This is a local operation
and makes no remote calls.
Permissions Required
None.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL
The idl file from which dce/sec_rgy_attr.h was derived.
ERRORS
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_cursor_init
sec_rgy_attr_cursor_alloc
sec_rgy_attr_lookup_by_id
107 – sec_rgy_attr_delete
NAME
sec_rgy_attr_delete - Deletes specified attributes for a specified
object
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_delete (
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
unsigned32 num_to_delete,
sec_attr_t attrs[],
signed32 *failure_index,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
A value of type sec_rgy_domain_t that identifies the registry
domain in which the object identified by name resides. The valid
values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
This parameter is ignored if name is policy or replist.
name A character string of type sec_rgy_name_t specifying the name
of the person, group, or organization to which the attributes
are attached.
num_to_delete
A 32-bit integer that specifies the number of elements in the
attrs[] array. This integer must be greater than 0.
attrs[]
An array of values of type sec_attr_t that specifies the
attribute instances to be deleted. The size of the array is
determined by num_to_delete.
Output
failure_index
In the event of an error, failure_index is a pointer to the
element in the in_attrs[] array that caused the update to fail.
If the failure cannot be attributed to a specific attribute, the
value of failure_index is -1.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_delete() routine deletes attributes. This is an atomic
operation: if the deletion of any attribute in the attrs[] array fails,
all deletions are aborted. The attribute causing the delete to fail is
identified in failure_index. If the failure cannot be attributed to a
given attribute, failure_index contains -1.
The attrs array, which specifies the attributes to be deleted, contains
values of type sec_attr_t These values consist of:
+ attr_id, a UUID that identifies the attribute type
+ attr_value, values of sec_attr_value_t that specify the
attribute's encoding type and values.
To delete attributes that are not multi-valued and to delete all
instances of a multi-valued attribute, an attribute UUID is all that
is required. For these attribute instances, supply the attribute
UUID in the input array and set the attribute encoding (in
sec_attr_encoding_t) to sec_attr_enc_void.
To delete a specific instance of a multi-valued attribute, supply the
UUID and value that uniquely identify the multi-valued attribute
instance in the input array.
Note that if the deletion of any attribute instance in the array fails,
all fail. However, to help pinpoint the cause of the failure, the call
identifies the first attribute whose deletion failed in a failure index
by array element number.
Permissions Required
The sec_rgy_attr_delete() routine requires the delete permission set
for each attribute type identified in the attrs[] array. These
permissions are defined as part of the ACL manager set in the schema
entry for the attribute type.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL
The idl file from which dce/sec_rgy_attr.h was derived.
ERRORS
unauthorized
database read only
server unavailable
invalid/unsupported attribute type
site read only
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_update
108 – sec_rgy_attr_get_effective
NAME
sec_rgy_attr_get_effective - Reads effective attributes by ID
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_get_effective(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
unsigned32 num_attr_keys,
sec_attr_t attr_keys[],
sec_attr_vec_t *attr_list,
error_status_t status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
A value of type sec_rgy_domain_t that identifies the domain in
which the named object resides. The valid values are as follows:
sec_rgy_domain_principal
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
This parameter is ignored if name is policy or replist.
name A pointer to a sec_rgy_name_t character string containing the
name of the person, group, or organization to which the
attribute is attached.
num_attr_keys
An unsigned 32-bit integer that specifies the number of elements
in the the attr_keys[] array. If num_attr_keys is set to 0,
all of the effective attributes that the caller is authorized to
see are returned.
attr_keys[]
An array of values of type sec_attr_t that specify the UUIDs
of the attributes to be returned if they are effective. If the
attribute type is associated with a query attribute trigger,
the sec_attr_t attr_value field can be used to pass in optional
information required by the attribute trigger query. If no
information is to be passed in the attr_value field (whether
the type indicates an attribute trigger query or not), set the
attribute's encoding type to sec_rgy_attr_enc_void. The size
of the attr_keys[] array is determined by the num_attr_keys
parameter.
Output
attr_list
A pointer an attribute vector allocated by the server containing
all of the effective attributes matching the search criteria
(defined in num_attr_keys or attr_keys[] ). The server
allocates a buffer large enough to return all the requested
attributes so that subsequent calls are not necessary.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_get_effective() routine returns the UUIDs of a
pecified object's effective attributes. Effective attributes are
determined by setting of the schema entry apply_defaults flag:
+ If the flag is set off, only the attributes directly attached
to the object are effective.
+ If the flag is set on, the effective attributes are obtained by
performing the following steps for each attribute identified by
UUID in the attr_keys array:
1. If the object named by name is a principal and if the a
requested attribute exists on the principal, that attribute
is effective and is returned. If it does not exist, the
search continues.
2. The next step in the search depends on the type of object:
For principals with accounts:
a. The organization named in the principal's account is
examined to see if an attribute of the requested type
exists. If it does, it is effective and is returned;
then the search for that attribute ends. If it does
not exist, the search for that attribute continues to
the policy object as described in b, below.
b. The registry policy object is examined to see if an
attribute of the requested type exits. If it does, it
is returned. If it does not, a message indicating the
no attribute of the type exists for the object is
returned.
For principals without accounts, for groups, and for organizations:
the registry policy object is examined to see if an attribute of
the requested type exits. If it does, it is returned. If it does
not, a message indicating the no attribute of the type exists for
the object is returned.
For multi-valued attributes, the call returns a sec_attr_t for each
value as an individual attribute instance. For attribute sets, the
call returns a sec_attr_t for each member of the set; it does not
return the set instance.
If the attribute instance to be read is associated with a query
attribute trigger that requires additional information before it
can process the query request, use a sec_attr_value_t to supply the
requested information. To do this:
+ Set the sec_attr_encoding_t to an encoding type that is compatible
with the information required by the query attribute trigger.
+ Set the sec_attr_value_t to hold the required information.
If the attribute instance to be read is not associated with a query
trigger or no additional information is required by the query trigger,
an attribute UUID is all that is required. For these attribute
instances, supply the attribute UUID in the input array and set the
attribute encoding (in sec_attr_encoding_t) to sec_attr_enc_void.
If the requested attribute type is associated with a query trigger,
the value returned for the attribute will be the binding (as set in
the schema entry) of the trigger server. The caller must bind to the
trigger server and pass the original input query attribute to the
sec_attr_trig_query call in order to retrieve the attribute value.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL
The idl file from which dce/sec_rgy_attr.h was derived.
ERRORS
error_status_ok
RELATED INFORMATION
Functions: sec_intro
109 – sec_rgy_attr_lookup_by_id
NAME
sec_rgy_attr_lookup_by_id - Reads a specified object's attribute(s),
expanding attribute sets into individual
member attributes
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_lookup_by_id (
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
sec_attr_cursor_t *cursor,
unsigned32 num_attr_keys,
unsigned32 space_avail,
sec_attr_t attr_keys[],
unsigned32 *num_returned,
sec_attr_t attrs[],
unsigned32 *num_left,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
A value of type sec_rgy_domain_t that identifies the registry
domain in which the object specified by name resides. The valid
values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
This parameter is ignored if name is policy or replist.
name A pointer to a sec_rgy_name_t character string containing the
name of the person, group, or organization to which the
attribute is attached.
num_attr_keys
An unsigned 32-bit integer that specifies the number of elements
in the attr_keys array. Set this parameter to 0 to return all
of the object's attributes that the caller is authorized to see.
space_avail
An unsigned 32-bit integer that specifies the size of the
attr_keys array.
attr_keys[]
An array of values of type sec_attr_t that identify the attribute
type ID of the attribute instance(s) to be looked up. If the
attribute type is associated with a query attribute trigger,
the sec_attr_t attr_value field can be used to pass in optional
information required by the attribute trigger query. If no
information is to be passed in the attr_value field (whether
the type indicates an attribute trigger query or not), set the
attribute's encoding type to sec_rgy_attr_enc_void. The size
of the attr_keys[] array is determined by the num_attr_keys
parameter.
Input/Output
cursor
A pointer to a sec_attr_cursor_t. As an input parameter, cursor
is a pointer to a sec_attr_cursor_t initialized by a
sec_rgy_attr_srch_cursor_init call. As an output parameter,
cursor is a pointer to a sec_attr_cursor_t that is positioned
past components returned in this call.
Output
num_returned
A pointer to a 32-bit unsigned integer that specifies the number
of attribute instances returned in the attrs[] array.
attrs An array of values of type sec_attr_t that contains the
attributes retrieved by UUID. The size of the array is
determined by space_avail and the length by num_returned.
num_left
A pointer to a 32-bit unsigned integer that supplies the number
of attributes that were found but could not be returned because
of space constraints in the attrs[] buffer. To ensure that all
the attributes will be returned, increase the size of the
attrs[] array by increasing the size of space_avail and
num_returned.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok, or, if the requested
attributes were not available, it returns the message
not_all_available. Otherwise, it returns an error.
DESCRIPTION
The sec_rgy_attr_lookup_by_id() function reads those attributes
specified by UUID for an object specified by name. This routine is
similar to the sec_rgy_attr_lookup_no_expand routine with one
exception: for attribute sets, the sec_rgy_attr_lookup_no_expand
routine returns a sec_attr_t for the set instance only; it does not
expand the set and return a sec_attr_t for each member in the set.
This call expands attribute sets and returns a sec_attr_t for each
member in the set.
If the num_attr_keys parameter is set to 0, all of the object's
attributes that the caller is authorized to see are returned. This
routine is useful for programmatic access.
For multi-valued attributes, the call returns a sec_attr_t for each
value as an individual attribute instance. For attribute sets, the call
returns a sec_attr_t for each member of the set; it does not return
the set instance.
The attr_keys[] array, which specifies the attributes to be returned,
contains values of type sec_attr_t. These values consist of:
+ attr_id, a UUID that identifies the attribute type
+ attr_value, values of sec_attr_value_t that specify the attribute's
encoding type and values.
Use the attr_id field of each attr_keys array element, to specify the
UUID that identifies the attribute type to be returned.
If the attribute instance to be read is not associated with a query
trigger or no additional information is required by the query trigger,
an attribute UUID is all that is required. For these attribute
instances, supply the attribute UUID in the input array and set the
attribute encoding (in sec_attr_encoding_t) to sec_attr_enc_void.
If the attribute instance to be read is associated with a query
attribute trigger that requires additional information before it
can process the query request, use a sec_attr_value_t to supply the
requested information.
To do this:
+ Set the sec_attr_encoding_t to an encoding type that is compatible
with the information required by the query attribute trigger.
+ Set the sec_attr_value_t to hold the required information.
Note that if you set num_attr_keys to zero to return all of the object's
attributes and that attribute is associated with a query attribute
trigger, the attribute trigger will be called with no input attribute
information (that would normally have been passed in via the attr_value
field).
The cursor parameter specifies a cursor of type sec_attr_cursor_t
initialized to the point in the attribute list at which to start
processing the query. Use the sec_attr_cursor_init function to
initialize cursor. If cursor is uninitialized, the server begins
processing the query at the first attribute that satisfies the search
criteria.
The num_left parameter contains the number of attributes that were
found but could not be returned because of space constraints of the
attrs[] array. (Note that this number may be inaccurate if the target
server allows updates between successive queries.) To obtain all of the
remaining attributes, set the size of the attrs[] array so that it is
large enough to hold the number of attributes listed in num_left.
Permissions Required
The sec_rgy_attr_lookup_by_id() routine requires the query permission
set for each attribute type identified in the attr_keys[] array. These
permissions are defined as part of the ACL manager set in the schema
entry of each attribute type.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL
The idl file from which dce/sec_rgy_attr.h was derived.
ERRORS
unauthorized
registry server unavailable
trigger server unavailable
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_lookup_no_expand
sec_rgy_attr_attr_lookup_by_name
110 – sec_rgy_attr_lookup_by_name
NAME
sec_rgy_attr_lookup_by_name - Read a single attribute instance for a
specific object
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_lookup_by_name(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
char *attr_name,
sec_attr_t *attr,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
A value of type sec_rgy_domain_t that identifies the domain in
which the named object resides. The valid values are as follows:
sec_rgy_domain_principal
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
This parameter is ignored if name is policy or replist.
name A pointer to a sec_rgy_name_t character string containing
the name of the person, group, or organization to which the
attribute is attached.
attr_name
An pointer to a character string that specifies the name of the
attribute to be retrieved.
Output
attr A pointer to a sec_attr_t that contains the first instance
of the named attribute.
status
A pointer to the completion status. The completion status can
be one of the following:
+ error_status_ok if all instances of the value are returned
with no errors.
+ more_available if a multi-valued attribute was specified
as name and the routine completed successfully. For multi-
valued attributes, this routine returns the first instance
of the attribute.
+ attribute_set_instance if an attribute set was specified
as name and the routine completed successfully.
+ An error message is the routine did not complete
successfully.
DESCRIPTION
The sec_rgy_attr_lookup_by_name() routine returns the named attribute
for a named object. This routine is useful for an interactive editor.
For multi-valued attributes, this routine returns the first instance
of the attribute. To retrieve every instance of the attribute, use the
sec_rgy_attr_lookup_by_id call, supplying the attribute UUID returned
in the attr parameter.
For attribute sets, the routine returns the attribute set instance,
not the member instances. To retrieve all members of the set, use the
sec_rgy_attr_lookup_by_id call, supplying the the attribute set UUID
returned in the attr parameter.
Warning
This routine does not provide for input data to an attribute trigger
query operation. If the named attribute is associated with a query
attribute trigger, the attribute trigger will be called with no input
attribute value information.
Permissions Required
The sec_rgy_attr_lookup_by_name() routine requires the query permission
set for the attribute type of the attribute instance identified by
attr_name. These permissions are defined as part of the ACL manager
set in the schema entry of each attribute type
ERRORS
unauthorized
registry server unavailable
trigger server unavailable
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_lookup_by_id
sec_rgy_attr_lookup_no_expand
111 – sec_rgy_attr_lookup_no_expand
NAME
sec_rgy_attr_lookup_no_expand - Reads a specified object's
attribute(s), without expanding
attribute sets into individual
member attributes
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_lookup_no_expand(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
sec_attr_cursor_t *cursor,
unsigned32 num_attr_keys,
unsigned32 space_avail,
uuid_t attr_keys[],
unsigned32 *num_returned,
sec_attr_t attr_sets[],
unsigned32 *num_left,
error_status_t status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
A value of type sec_rgy_domain_t that identifies the domain
in which the named object resides. The valid values are as
follows:
sec_rgy_domain_principal
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
This parameter is ignored if name is policy or replist.
name A pointer to a sec_rgy_name_t character string containing the
name of the person, group, or organization to which the
attribute is attached.
num_attr_keys
An unsigned 32-bit integer that specifies the number of elements
in the the attr_keys[] array. If num_attr_keys is set to 0, all
attribute sets that the caller is authorized to see are returned.
space_avail
An unsigned 32-bit integer that specifies the size of the
attrs_sets[] array.
attr_keys[]
An array of values of type uuid_t that specify the UUIDs of
the attribute sets to be returned. The size of the attr_keys[]
array is determined by the num_attr_keys parameter.
Input/Output
cursor
A pointer to a sec_attr_cursor_t. As an input parameter,
cursor is a pointer to a sec_attr_cursor_t that is initialized
by the sec_rgy_attr_cursor_init. As an output parameter,
cursor is a pointer to a sec_attr_cursor_t that is positioned
past the attribute sets returned in this call.
Output
num_returned
A pointer to a 32-bit integer that specifies the number of
attribute sets returned in the attrs[] array.
attr_sets
An array of values of type sec_attr_t that contains the
attribute sets retrieved by UUID. The size of the array is
determined by space_avail and the length by num_returned.
num_left
A pointer to a 32-bit unsigned integer that supplies the number
of attribute sets that were found but could not be returned
because of space constraints in the attr_sets[] buffer. To
ensure that all the attributes will be returned, increase the
size of the attr_sets[] array by increasing the size of
space_avail and num_returned.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_lookup_no_expand() routine reads attribute sets. This
routine is similar to the sec_rgy_attr_lookup_by_id() routine with one
exception: for attribute sets, the sec_rgy_attr_lookup_by_id() routine
expands attribute sets and returns a sec_attr_t for each member in the
set. This call does not. Instead it returns a sec_attr_t for the set
instance only. The sec_rgy_attr_lookup_no_expand() routine is useful
for programmatic access.
cursor is a cursor of type sec_attr_cursor_t that establishes the point
in the attribute set list from which the server should start processing
the query. Use the sec_rgy_attr_cursor_init function to initialize
cursor. If cursor is uninitialized, the server begins processing the
query with the first attribute that satisfies the search criteria.
The num_left parameter contains the number of attribute sets that were
found but could not be returned because of space constraints of the
attr_sets[] array. (Note that this number may be inaccurate if the
target server allows updates between successive queries.) To obtain all
of the remaining attribute sets, set the size of the attr_sets[] array
so that it is large enough to hold the number of attributes listed in
num_left.
Permissions Required
The sec_rgy_attr_lookup_no_expand() routine requires the query
permission set for each attribute type identified in the attr_keys[]
array. These permissions are defined as part of the ACL manager set
in the schema entry of each attribute type.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL
The idl file from which dce/sec_rgy_attr.h was derived.
ERRORS
unauthorized
registry server unavailable
invalid/unsupported attribute type
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_lookup_by_id
sec_rgy_attr_lookup_by_name
112 – sec_rgy_attr_sch_aclmgr_strings
NAME
sec_rgy_attr_sch_aclmgr_strings - Returns printable ACL strings
associated with an ACL manager
protecting a bound to schema
object
SYNOPSIS
#include <dce/dce_attr_base.h>
void sec_rgy_attr_sch_aclmgr_strings(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
uuid_t *acl_mgr_type,
unsigned32 size_avail,
uid_t *acl_mgr_type_chain,
sec_acl_printstring_t *acl_mgr_info,
boolean32 *tokenize,
unsigned32 *total_num_printstrings,
unsigned32 *size_used,
sec_acl_printstring_t permstrings[],
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
schema_name
Reserved for future use.
acl_manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the schema object whose ACL is bound to the input
handle. Use this parameter to distinguish them. Use
sec_rgy_attr_sch_get_acl_mgrs to acquire a list of the manager
types protecting a given schema object.
size_avail
An unsigned 32-bit integer containing the allocated length of
the permstrings[] array.
Output
acl_mgr_type_chain
If the target object ACL contains more than 32 permission bits,
chains of manager types are used: each manager type holds one
32-bit segment of permissions. The UUID returned in
acl_mgr_type_chain refers to the next ACL manager in the chain.
If there are no more ACL managers in the chain, uuid_nil is
returned.
acl_mgr_info
A pointer to a printstring that contains the ACL manager type's
name, help information, and set of supported of permission bits.
tokenize
A pointer to a variable that specifies whether or not
printstrings will be passed separately:
+ TRUE indicates that the printstrings must be printed or
passed separately.
+ FALSE indicates that the printstrings are unambiguous and
can be concatenated when printed without confusion.
total_num_printstrings
A pointer to an unsigned 32-bit integer containing the total
number of permission entries supported by this ACL manager type.
size_used
A pointer to an unsigned 32-bit integer containing the number
of permission entries returned in the permstrings[] array.
permstrings[]
An array of printstrings of type sec_acl_printstring_t.
Each entry of the array is a structure containing the
following three components:
printstring
A character string of maximum length
sec_acl_printstring_len describing the printable
representation of a specified permission.
helpstring
A character string of maximum length
sec_acl_printstring_help_len containing some text that
can be used to describe the specified permission.
permissions
A sec_acl_permset_t permission set describing the
permissions that are represented with the companion
printstring.
The array consists of one such entry for each permission supported by
the ACL manager identified by acl_mgr_type.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_aclmgr_strings() routine returns an array of
printable representations (called "printstrings") for each permission
bit or combination of permission bits the specified ACL manager
supports. The ACL manager type specified by acl_mgr_type must be one
of the types protecting the schema object bound to by h.
In addition to returning the printstrings, this routine also returns
instructions about how to print the strings in the tokenize variable.
If this variable is set to FALSE, the printstrings can be concatenated.
If it is set to TRUE, the printstrings cannot be concatenated. For
example a printstrings of r or w could be concatenated as rw without
any confusion. However, printstrings in a form of read or write,
should not be concatenated.
ACL managers often define aliases for common permission combinations.
By convention, simple entries appear at the beginning of the
printstrings[] array, and combinations appear at the end.
Permissions Required
The sec_rgy_attr_sch_scl_mgr_strings() routine requires the r permission
on the attr_schema object.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_get_acl_mgrs
113 – sec_rgy_attr_sch_create_entry
NAME
sec_rgy_attr_sch_create_entry - Create a schema entry
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_create_entry(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
sec_attr_schema_entry_t *schema_entry,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
schema_name
Reserved for future use.
schema_entry
A pointer to a sec_attr_schema_entry_t that contains the schema
entry values for the schema in which the entry is to be created.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_create_entry() routine creates schema entries that
define attribute types.
Permissions Required
The sec_rgy_attr_sch_create_entry() routine requires i permission
on the attr_schema object.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_bad_name
sec_attr_bad_encoding_type
sec_attr_bad_acl_mgr_set
sec_attr_bad_acl_mgr_type
sec_attr_bad_permset
sec_attr_bad_intercell_action
sec_attr_trig_bind_info_missing
sec_attr_bad_bind_info
sec_attr_bad_bind_svr_name
sec_attr_bad_bind_prot_level
sec_attr_bad_bind_authn_svc
sec_attr_bad_bind_authz_svc
sec_attr_bad_uniq_query_accept
sec_attr_bad_scope
sec_attr_bad_comment
sec_attr_type_id_exists
sec_attr_name_exists
sec_attr_unauthorized
sec_attr_svr_read_only
sec_attr_svr_unavailable
sec_attr_no_memory
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_delete_entry
sec_rgy_attr_sch_update
114 – sec_rgy_attr_sch_cursor_alloc
NAME
sec_rgy_attr_sch_cursor_alloc - Allocates resources to a cursor
used with the sec_rgy_attr_sch_scan
call
SYNOPSIS
void sec_rgy_att_sch_cursor_alloc(
dce_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Output
cursor
A pointer to a sec_attr_cursor_t.
status
A pointer to the completion status. On successful completion,
the call returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_cursor_alloc() call allocates resources to a
cursor used with the sec_rgy_attr_sch_scan() call. This routine,
which is a local operation, does not initialize cursor.
The sec_rgy_attr_sch_cursor_init() routine, which makes a remote
call, allocates and initializes the cursor. In addition,
sec_rgy_attr_sch_cursor_init() returns the total number of entries
found in the schema as an output parameter;
sec_rgy_attr_sch_cursor_alloc() does not.
Permissions Required
None.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.id was
derived.
ERRORS
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_cursor_init
sec_rgy_attr_sch_cursor_release
sec_rgy_attr_sch_scan
115 – sec_rgy_attr_sch_cursor_init
NAME
sec_rgy_attr_sch_cursor_init - Initialize and allocate a cursor used
with the sec_rgy_attr_sch_scan call
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_cursor_init(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
unsigned32 *cur_num_entries,
sec_attr_cursor_t *cursor,
error_status_t status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
schema_name
Reserved for future use.
Output
cur_num_entries
A pointer to an unsigned 32-bit integer that specifies the
total number of entries contained in the schema at the time
of this call.
cursor
A pointer to a sec_attr_cursor_t that is initialized to the
first entry in the the schema.
status
A pointer to the completion status. On successful completion,
the call returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_cursor_init() call initializes and allocates
resources to a cursor used with the sec_rgy_attr_sch_scan call. This
call makes remote calls to initialize the cursor. To limit the number
of remote calls, use the sec_rgy_attr_sch_cursor_alloc() call to
allocate cursor, but not initialize it. Be aware, however, that the
sec_rgy_attr_sch_cursor_init() call supplies the total number of entries
found in the schema as an output parameter; the
sec_rgy_attr_sch_cursor_alloc() call does not.
If the cursor iunput to sec_rgy_attr_sch_scan has not been initialized,
the sec_rgy_attr_sch_scan call will initialize it; if it has been
initialized, sec_rgy_attr_sch_scan advances it.
Permissions Required
None.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_cursor_release
sec_rgy_attr_sch_scan
sec_rgy_attr_sch_cursor_alloc
116 – sec_rgy_attr_sch_cursor_release
NAME
sec_rgy_attr_sch_cursor_release - Release states associated
with a cursor used by the
sec_rgy_attr_sch_scan routine
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_cursor_release(
sec_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input/Output
cursor
A pointer to a sec_attr_cursor_t. As an input parameter, cursor
must have been initialized to the first entry in a schema. As
an output parameter, cursor is uninitialized with all resources
releases.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_cursor_init() routine releases the resources
allocated to the cursor used by the sec_rgy_attr_sch_scan routine.
This call is a local operation and makes no remote calls.
Permissions Required
None.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_cursor_init
sec_rgy_attr_sch_cursor_allocate
sec_rgy_attr_sch_scan
117 – sec_rgy_attr_sch_cursor_reset
NAME
sec_rgy_attr_sch_cursor_reset - Resets a cursor that has been
allocated with either
sec_rgy_attr_sch_cursor_init() or
sec_rgy_attr_sch_cursor_alloc().
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void dce_attr_cursor_reset(
sec_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input/Output
cursor
A pointer to a sec_attr_cursor_t. As an input parameter, an
initialized cursor. As an output parameter, cursor is reset
to the first attribute in the schema.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_cursor_reset() routine resets a dce_attr_cursor_t
that has been allocated by either a sec_rgy_attr_sch_cursor_init() or
sec_rgy_attr_sch_cursor_alloc(). The reset cursor can then be used to
process a new sec_rgy_attr_sch_scan query by reusing the cursor instead
of releasing and re-allocating it. This is a local operation and makes
no remote calls.
Permissions Required
None.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_bad_cursor
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_cursor_init
sec_rgy_attr_sch_cursor_alloc
sec_rgy_attr_sch_scan
118 – sec_rgy_attr_sch_delete_entry
NAME
sec_rgy_attr_sch_delete_entry - Delete a schema entry
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_delete_entry(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
uuid_t *attr_id,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
schema_name
Reserved for future use.
attr_id
A pointer to a uuid_t that identifies the schema entry to be
deleted.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_delete_entry() routine deletes a schema entry.
Because this is a radical operation that invalidates any existing
attributes of this type on objects dominated by the schema, access to
this operation should be severely limited.
Permissions Required
The sec_rgy_attr_sch_delete_entry() routine requires the d permission
on the attr_schema object.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_sch_entry_not_found
sec_attr_unauthorized
sec_attr_svr_read_only
sec_attr_svr_unavailable
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_create_entry
sec_rgy_attr_sch_update_entry
119 – sec_rgy_attr_sch_get_acl_mgrs
NAME
sec_rgy_attr_sch_get_acl_mgrs - Retrieve the manager types of the
ACLs protecting the objects
dominated by a named schema
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_get_acl_mgrs(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_acl_mgr_types,
uuid_t acl_mgr_types[],
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
schema_name
Reserved for future use.
size_avail
An unsigned 32-bit integer containing the allocated length of
the acl_manager_types[] array.
Output
size_used
An unsigned 32-bit integer containing the number of output
entries returned in the acl_mgr_types[] array.
num_acl_mgr_types
An unsigned 32-bit integer containing the number of types
returned in the acl_mgr_types[] array. This may be greater
than size_used if there was not enough space allocated by
size_avail for all the manager types in the
acl_manager_types[] array.
acl_mgr_types[]
An array of the length specified in size_avail to contain UUIDs
(of type uuid_t) identifying the types of ACL managers protecting
the target object.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_get_acl_mgrs() routine returns a list of the
manager types protecting the schema object identified by context.
ACL editors and browsers can use this operation to determine the ACL
manager types protecting a selected schema object. Then, using the
sec_rgy_attr_sch_aclmgr_strings() routine, they can determine how to
format for display the permissions supported by that ACL manager type.
Permissions Required
The sec_rgy_attr_sch_get_acl_mgrs() routine requires the r permission
on the attr_schema object.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_aclmgr_strings
120 – sec_rgy_attr_sch_lookup_by_id
NAME
sec_rgy_attr_sch_lookup_by_id - Read a schema entry identified by UUID
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_lookup_by_id(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
uuid_t *attr_id,
sec_attr_schema_entry_t *schema_entry,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
schema_name
Reserved for future use.
attr_id
A pointer to a uuid_t that identifies a schema entry.
Output
schema_entry
A sec_attr_schema_entry_t that contains an entry identified by
attr_id.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_lookup_by_id() routine reads a schema entry
identified by attr_id. This routine is useful for programmatic access.
Permissions Required
The sec_rgy_attr_sch_lookup_by_id() routine requires the r permission
on the attr_schema object.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_sch_entry_not_found
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_lookup_by_name
sec_rgy_attr_sch_scan
121 – sec_rgy_attr_sch_lookup_by_name
NAME
sec_rgy_attr_sch_lookup_by_name - Read a schema entry identified by
name
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_lookup_by_name(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
char *attr_name,
sec_attr_schema_entry_t *schema_entry,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
schema_name
Reserved for future use.
attr_name
A pointer to a character string that identifies the schema entry.
Output
schema_entry
A sec_attr_schema_entry_t that contains the schema entry
identified by attr_name.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_lookup_by_name() routine reads a schema entry
identified by name. This routine is useful for use with an interactive
editor.
Permissions Required
The sec_rgy_attr_sch_lookup_by_name() routine requires the r permission
on the attr_schema object.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_sch_entry_not_found
sec_attr_bad_name
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_lookup_by_id
sec_rgy_attr_sch_scan
122 – sec_rgy_attr_sch_scan
NAME
sec_rgy_attr_sch_scan - Read a specified number of schema entries
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_scan(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
sec_attr_cursor_t *cursor,
unsigned32 num_to_read,
unsigned32 *num_read,
sec_attr_schema_entry_t schema_entries[],
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
schema_name
Reserved for future use.
num_to_read
An unsigned 32-bit integer specifying the size of the
schema_entries[] array and the maximum number of entries to be
returned.
Input/Output
cursor
A pointer to a sec_attr_cursor_t. As input cursor must be
allocated and can be initialized. If cursor is not initialized,
sec_rgy_attr_sch_scan will initialized. As output, cursor is
positioned at the first schema entry after the returned entries.
Output
num_read
A pointer an unsigned 32-bit integer specifying the number of
entries returned in schema_entries[].
schema_entries[]
A sec_attr_schema_entry_t that contains an array of the returned
schema entries.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_scan() routine reads schema entries. The read
begins at the entry at which the input cursor is positioned and ends
after the number of entries specified in num_to_read.
The input cursor must have been allocated by either the
sec_rgy_attr_sch_cursor_init() or the sec_rgy_attr_sch_cursor_alloc()
call. If the input cursor is not initialzed, sec_rgy_attr_sch_scan()
initializes it; if cursor is initialized, sec_rgy_attr_sch_scan()
simply advances it.
To read all entries in a schema, make successive sec_rgy_attr_sch_scan()
calls. When all entries have been read, the call returns the message
no_more_entries.
This routine is useful as a browser.
Permissions Required
The sec_rgy_attr_sch_scan() routine requires r permission on the
attr_schema object.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_bad_cursor
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_cursor_init
sec_rgy_attr_sch_cursor_alloc
sec_rgy_attr_sch_cursor_release
123 – sec_rgy_attr_sch_update_entry
NAME
sec_rgy_attr_sch_update_entry - Update a schema entry
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_update_entry(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
sec_attr_schema_entry_parts_t modify_parts,
sec_attr_schema_entry_t *schema_entry,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
schema_name
Reserved for future use.
modify_parts
A value of type sec_attr_schema_entry_parts_t that identifies the
fields in schema_entry that can be modified.
schema_entry
A pointer to a sec_attr_schema_entry_t that contains the schema
entry values for the schema entry to be updated.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_update_entry() routine modifies schema entries.
Only those schema entry fields set to be modified in the
sec_attr_schema_entry_parts_t data type can be modified.
Some schema entry components can never be modified. Instead to make any
changes to these components, the schema entry must be deleted (which
deletes all attribute instances of that type) and recreated. The schema
entry components that can never be modified are listed below:
+ Attribute name
+ Reserved flag
+ Apply defaults flag
+ Intercell action flag
+ Trigger binding
+ Comment
Fields that are arrays of structures (such as acl_mgr_set and
trig_binding) are completely replaced by the new input array. This
operation cannot be used to add a new element to the existing array.
Permissions Required
The sec_rgy_attr_sch_update_entry() routine requires the M permission
on the attr_schema object.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_field_no_update
sec_attr_bad_name
sec_attr_bad_acl_mgr_set
sec_attr_bad_acl_mgr_type
sec_attr_bad_permset
sec_attr_bad_intercell_action
sec_attr_trig_bind_info_missing
sec_attr_bad_bind_info
sec_attr_bad_bind_svr_name
sec_attr_bad_bind_prot_level
sec_attr_bad_bind_authn_svc
sec_attr_bad_bind_authz_svc
sec_attr_bad_uniq_query_accept
sec_attr_bad_comment
sec_attr_name_exists
sec_attr_sch_entry_not_found
sec_attr_unauthorized
sec_attr_svr_read_only
sec_attr_svr_unavailable
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_delete_entry
sec_rgy_attr_sch_create_entry
124 – sec_rgy_attr_test_and_update
NAME
sec_rgy_attr_test_and_update - Updates specified attribute instances
for a specified object only if a set
of control attribute instances match
the object's existing attribute instances
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_test_and_update (
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
unsigned32 num_to_test,
sec_attr_t test_attrs[],
unsigned32 num_to_write,
sec_attr_t update_attrs[],
signed32 *failure_index,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
A value of type sec_rgy_domain_t that identifies the registry
domain in which the object specified by name resides. The valid
values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
This parameter is ignored if name is policy or replist.
name A character string of type sec_rgy_name_t specifying the name
of the person, group, or organization to which the attribute
is attached.
num_to_test
An unsigned 32-bit integer that specifies the number of elements
in the test_attrs[] array. This integer must be greater than 0.
test_attrs[]
An array of values of type sec_attr_t that specifies the control
attributes. The update takes place only if the types and values
of the control attributes exactly match those of the attribute
instances on the named registry object. The size of the array is
determined by num_to_test.
num_to_write
A 32-bit integer that specifies the number of attribute
instances returned in the update_attrs[] array.
update_attrs
An array of values of type sec_attr_t that specifies the
attribute instances to be updated. The size of the array is
determined by num_to_write.
Output
failure_index
In the event of an error, failure_index is a pointer to the
element in the update_attrs[] array that caused the update to
fail. If the failure cannot be attributed to a specific
attribute, the value of failure_index is -1.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_test_and_update() routine updates an attribute only
if the set of control attributes specified in the test_attrs[] match
attributes that already exist for the object.
This update is an atomic operation: if any of the control attributes
do not match existing attributes, none of the updates are performed,
and if an update should be performed, but the write cannot occur for
whatever reason to any member of the update_attrs[] array, all updates
are aborted. The attribute causing the update to fail is identified in
failure_index. If the failure cannot be attributed to a given attribute,
failure_index contains -1.
If an attribute instance already exists which is identical in both
attr_id and attr_value to an attribute specified in in_attrs[], the
existing attribute information is overwritten by the new information.
For multi-valued attributes, every instance with the same attr_id is
overwritten with the supplied values.
If an attribute instance does not exist, it is created.
If you specify an attribute set for updating, the update applies to the
set instance, the set itself, not the members of the set. To update a
member of an attribute set, supply the UUID of the set member.
If an input attribute is associated with an update attribute trigger
server, the attribute trigger server is invoked (by the
sec_attr_trig_update() function) and the in_attr[] array is supplied
as input. The output attributes from the update attribute trigger server
are stored in the registry database and returned in the out_attrs[]
array. Note that the update attribute trigger server may modify the
values before they are used to update the registry database. This is
the only circumstance under which the values in the out_attrs[] array
differ from the values in the in_attrs[] array.
Permissions Required
The sec_rgy_attr_test_and_update() routine routine requires the test
permission and the update permission set set for each attribute type
identified in the test_attrs[] array. These permissions are defined as
part of the ACL manager set in the schema entry of each attribute type.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL
The idl file from which dce/sec_rgy_attr.h was derived.
ERRORS
control attribute has changed
unauthorized
database read only
server unavailable
invalid/unsupported attribute type
invalid encoding type
value not unique
trigger server unavailable
site read only
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_update
sec_rgy_attr_delete
125 – sec_rgy_attr_update
NAME
sec_rgy_attr_update - Creates and updates attribute instances for a
specified object
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_update (
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
unsigned32 num_to_write,
unsigned32 space_avail,
sec_attr_t in_attrs[],
unsigned32 *num_returned,
sec_attr_t out_attrs[],
unsigned32 *num_left,
signed32 *failure_index,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
A value of type sec_rgy_domain_t that identifies the registry
domain in which the object specified by name resides. The
valid values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
This parameter is ignored if name is policy or replist.
name A character string of type sec_rgy_name_t specifying the name
of the person, group, or organization to which the attribute
is attached.
num_to_write
A 32-bit unsigned integer that specifies the number of elements
in the in_attrs array. This integer must be greater than 0.
space_avail
A 32-bit unsigned integer that specifies the size of the
out_attrs array. This integer must be greater than 0.
in_attrs[]
An array of values of type sec_attr_t that specifies the
attribute instances to be updated. The size of the array is
determined by num_to_write.
Output
num_returned
A pointer to an unsigned 32-bit integer that specifies the
number of attribute instances returned in the out_attrs[] array.
out_attrs
An array of values of type sec_attr_t that specifies the updated
attribute instances. Not that only if these attributes were
processed by an update attribute trigger server will they differ
from the attributes in the in_attrs[] array. The size of the
array is determined by space_avail and the length by
num_returned.
num_left
A pointer to an unsigned 32-bit integer that supplies the number
of attributes that could not be returned because of space
constraints in the out_attrs[] buffer. To ensure that all the
attributes will be returned, increase the size of the
out_attrs[] array by increasing the size of space_avail and
num_returned.
failure_index
In the event of an error, failure_index is a pointer to the
element in the in_attrs[] array that caused the update to fail.
If the failure cannot be attributed to a specific attribute,
the value of failure_index is -1.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_update() routine creates new attribute instances and
updates existing attribute instances attached to a object specified by
name and Registry domain. The instances to be created or updated are
passed as an array of sec_attr_t data types. This is an atomic
operation: if the creation of any attribute in the in_attrs[] array
fails, all updates are aborted. The attribute causing the update to
fail is identified in failure_index. If the failure cannot be
attributed to a given attribute, failure_index contains -1.
The in_attrs array, which specifies the attributes to be created,
contains values of type sec_attr_t. These values are:
+ attr_id, a UUID that identifies the attribute type
+ attr_value, values of sec_attr_value_t that specify the attribute's
encoding type and values.
If an attribute instance already exists which is identical in both
attr_id and attr_value to an attribute specified in in_attrs, the
existing attribute information is overwritten by the new information.
For multi-valued attributes, every instance with the same attr_id is
overwritten with the supplied values.
If an attribute instance does not exist, it is created.
For multi-valued attributes, because every instance of the multi-valued
attribute is identified by the same UUID, every instance is overwritten
with the supplied value. To change only one of the values, you must
supply the values that should be unchanged as well as the new value.
To create instances of multi-valued attributes, create individual
sec_attr_t data types to define each multi-valued attribute instance
and then pass all of them in in the input array.
If an input attribute is associated with an update attribute trigger
server, the attribute trigger server is invoked (by the
sec_attr_trig_update() function) and the in_attr[] array is supplied
as input. The output attributes from the update attribute trigger server
are stored in the registry database and returned in the out_attrs[]
array. Note that the update attribute trigger server may modify the
values before they are used to update the registry database. This is
the only circumstance under which the values in the out_attrs[] array
differ from the values in the in_attrs[] array.
Permissions Required
The sec_rgy_attr_update() routine requires the update permission set
for each attribute type identified in the in_attrs[] array. These
permissions are defined as part of the ACL manager set in the schema
entry of each attribute type.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL
The idl file from which dce/sec_rgy_attr.h was derived.
ERRORS
unauthorized
database read only
server unavailable
invalid/unsupported attribute type
invalid encoding type
value not unique
attribute instance already exists
trigger server unavailable
site read only
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_delete
sec_rgy_attr_test_and_update
126 – sec_rgy_auth_plcy_get_effective
NAME
sec_rgy_auth_plcy_get_effective - Returns the effective
authentication policy for an
account
SYNOPSIS
#include <dce/policy.h>
void sec_rgy_auth_plcy_get_effective(
sec_rgy_handle_t context,
sec_rgy_login_name_t *account,
sec_rgy_plcy_auth_t *auth_policy,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
account
A pointer to the account login name (type sec_rgy_login_name_t).
A login name is composed of three character strings, containing
the principal, group, and organization (PGO) names corresponding
to the account. If all three fields contain empty strings, the
authentication policy returned is that of the registry.
Output
auth_policy
A pointer to the sec_rgy_plcy_auth_t structure to receive the
authentication policy. The authentication policy structure
contains the maximum lifetime for an authentication ticket,
and the maximum amount of time for which one can be renewed.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_auth_plcy_get_effective() routine returns the effective
authentication policy for the specified account. The authentication
policy in effect is the more restrictive of the registry and the account
policies for each policy category. If no account is specified, the
registry's authentication policy is returned.
Permissions Required
The sec_rgy_auth_plcy_get_effective() routine requires the r (read)
permission on the policy object from which the data is to be returned.
If an account is specified and an account policy exists, the routine
also requires the r (read) permission on the account principal.
FILES
SYS$COMMON:[DCE$LIBRARY]POLICY.IDL
The idl file from which dce/policy.h was derived.
ERRORS
sec_rgy_object_not_found
The specified account could not be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_auth_plcy_get_info
sec_rgy_auth_plcy_set_info
127 – sec_rgy_auth_plcy_get_info
NAME
sec_rgy_auth_plcy_get_info - Returns the authentication policy for
an account
SYNOPSIS
#include <dce/policy.h>
void sec_rgy_auth_plcy_get_info(
sec_rgy_handle_t context,
sec_rgy_login_name_t *account,
sec_rgy_plcy_auth_t *auth_policy,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
account
A pointer to the account login name (type sec_rgy_login_name_t).
A login name is composed of three character strings, containing
the principal, group, and organization (PGO) names corresponding
to the account.
Output
auth_policy
A pointer to the sec_rgy_plcy_auth_t structure to receive the
authentication policy. The authentication policy structure
contains the maximum lifetime for an authentication ticket,
and the maximum amount of time for which one can be renewed.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_auth_plcy_get_info() routine returns the authentication
policy for the specified account. If no account is specified, the
registry's authentication policy is returned.
Permissions Required
The sec_rgy_auth_plcy_get_info() routine requires the r (read)
permission on the policy object or account principal from which the
data is to be returned.
NOTES
The actual policy in effect will not correspond precisely to what
is returned by this call if the overriding registry authentication
policy is more restrictive than the policy for the specified account.
Use sec_rgy_auth_plcy_get_effective() to return the policy currently
in effect for the given account.
FILES
SYS$COMMON:[DCE$LIBRARY]POLICY.IDL
The idl file from which dce/policy.h was derived.
ERRORS
sec_rgy_object_not_found
No account with the given login name could be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_auth_plcy_get_effective
sec_rgy_auth_plcy_set_info
128 – sec_rgy_auth_plcy_set_info
NAME
sec_rgy_auth_plcy_set_info - Sets the authentication policy for an
account
SYNOPSIS
#include <dce/policy.h>
void sec_rgy_auth_plcy_set_info(
sec_rgy_handle_t context,
sec_rgy_login_name_t *account,
sec_rgy_plcy_auth_t *auth_policy,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
account
A pointer to the account login name (type sec_rgy_login_name_t).
A login name is composed of three character strings, containing
the principal, group, and organization (PGO) names corresponding
to the account. All three names must be completely specified.
auth_policy
A pointer to the sec_rgy_plcy_auth_t structure containing the
authentication policy. The authentication policy structure
contains the maximum lifetime for an authentication ticket,
and the maximum amount of time for which one can be renewed.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_auth_plcy_set_info() routine sets the indicated
authentication policy for the specified account. If no account
is specified, the authentication policy is set for the registry
as a whole.
Permissions Required
The sec_rgy_auth_plcy_set_info() routine requires the a (auth_info)
permission on the policy object or account principal for which the
data is to be set.
NOTES
The policy set on an account may be less restrictive than the policy
set for the registry as a whole. In this case, the change in policy
has no effect, since the effective policy is the most restrictive
combination of the principal and registry authentication policies.
(See the sec_rgy_auth_plcy_get_effective() routine).
FILES
SYS$COMMON:[DCE$LIBRARY]POLICY.IDL
The idl file from which dce/policy.h was derived.
ERRORS
sec_rgy_object_not_found
No account with the given login name could be found.
sec_rgy_not_authorized
The user is not authorized to update the specified record.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_auth_plcy_get_effective
sec_rgy_auth_plcy_get_info
129 – sec_rgy_cell_bind
NAME
sec_rgy_cell_bind - Binds to a registry in a cell
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_cell_bind(
unsigned_char_t *cell_name,
sec_rgy_bind_auth_info_t *auth_info,
sec_rgy_handle_t *context,
error_status_t *status);
PARAMETERS
Input
cell_name
A character string (type unsigned_char_t) containing the name
of the cell in question. Upon return, a Security Server for
that cell is associated with context, the registry server
handle. The cell must be specified completely and precisely.
This routine offers none of the pathname resolving services
of sec_rgy_site_bind().
auth_info
A pointer to the sec_rgy_bind_auth_info_t structure that
identifies the authentication protocol, protection level,
and authorization protocol to use in establishing the
binding. (See the rpc_binding_set_auth_info() routine).
Output
context
A pointer to a sec_rgy_handle_t variable. Upon return, this
contains a registry server handle indicating ("bound to")
the desired registry site.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_cell_bind() routine establishes a relationship with a
registry site at an arbitrary level of security. The cell_name
parameter identifies the target cell.
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_bind
130 – sec_rgy_cursor_reset
NAME
sec_rgy_cursor_reset - Resets the registry database cursor
SYNOPSIS
#include <dce/misc.h>
void sec_rgy_cursor_reset(
sec_rgy_cursor_t *cursor);
PARAMETERS
Input/Output
cursor A pointer into the registry database.
DESCRIPTION
The sec_rgy_cursor_reset() routine resets the database cursor to
return the first suitable entry. A cursor is a pointer into the
registry. It serves as a place holder when returning successive
items from the registry.
A cursor is bound to a particular server. In other words, a cursor
that is in use with one replica of the registry has no meaning for
any other replica. If a calling program attempts to use a cursor
from one replica with another, the cursor is reset and the routine
for which the cursor was specified returns the first item in the
database.
A cursor that is in use with one call cannot be used with another.
For example, you cannot use the same cursor on a call to
sec_rgy_acct_get_projlist() and sec_rgy_pgo_get_next(). The behavior
in this case is undefined.
FILES
SYS$COMMON:[DCE$LIBRARY]MISC.IDL
The idl file from which dce/misc.h was derived.
EXAMPLES
The following example illustrates use of the cursor within a loop.
The initial sec_rgy_cursor_reset() call resets the cursor to point
to the first item in the registry. Successive calls to
sec_rgy_pgo_get_next() return the next PGO item and update the cursor
to reflect the last item returned. When the end of the list of PGO
items is reached, the routine returns the value sec_rgy_no_more_entries
in the status parameter.
sec_rgy_cursor_reset(&cursor);
do {
sec_rgy_pgo_get_next(context, domain, scope, &cursor,
&item, name &status);
if (status == error_status_ok) {
/* Print formatted PGO item info */
}
} while (status == error_status_ok);
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_get_projlist
sec_rgy_acct_lookup
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_get_members
sec_rgy_pgo_get_next
131 – sec_rgy_login_get_effective
NAME
sec_rgy_login_get_effective - Returns the effective login data for
an account
SYNOPSIS
#include <dce/misc.h>
void sec_rgy_login_get_effective(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_key_t *key_parts,
sec_rgy_sid_t *sid,
sec_rgy_unix_sid_t *unix_sid,
sec_rgy_acct_user_t *user_part,
sec_rgy_acct_admin_t *admin_part,
sec_rgy_plcy_t *policy_data,
signed32 max_number,
signed32 *supplied_number,
uuid_t id_projlist[],
signed32 unix_projlist[],
signed32 *num_projects,
sec_rgy_name_t cell_name,
uuid_t *cell_uuid,
sec_override_fields_t *overridden,
error_status_t *status);
PARAMETERS
Input
context
The registry server handle.
max_number
The maximum number of projects to be returned by the call.
This must be no larger than the allocated size of the
projlist[] arrays.
Input/Output
login_name
A pointer to the account login name. A login name is composed
of the names for the account's principal, group, and
organization (PGO) items.
Output
key_parts
A pointer to the minimum abbreviation allowed when logging in
to the account. Abbreviations are not currently implemented
and the only legal value is sec_rgy_acct_key_person.
sid A pointer to a sec_rgy_sid_t structure to receive the returned
Subject Identifier (SID) for the account. This structure
consists of the UUIDs for the account's PGO items.
unix_sid
A pointer to a sec_rgy_unix_sid_t structure to receive the
returned UNIX Subject Identifier (SID) for the account.
This structure consists of the UNIX numbers for the account's
PGO items.
user_part
A pointer to a sec_rgy_acct_user_t structure to receive the
returned user data for the account.
admin_part
A pointer to a sec_rgy_acct_admin_t structure to receive the
returned administrative data for the account.
policy_data
A pointer to a sec_rgy_policy_t structure to receive the policy
data for the account. The policy data is associated with the
account's organization, as identified in the login name.
supplied_number
A pointer to the actual number of projects returned. This
will always be less than or equal to the max_number supplied
on input.
id_projlist[]
An array to receive the UUID of each project returned. The size
allocated for the array is given by max_number. If this value
is less than the total number of projects in the account project
list, multiple calls must be made to return all of the projects.
unix_projlist[]
An array to receive the UNIX number of each project returned.
The size allocated for the array is given by max_number. If
this value is less than the total number of projects in the
account project list, multiple calls must be made to return
all of the projects.
num_projects
A pointer indicating the total number of projects in the
specified account's project list.
cell_name
The name of the account's cell.
cell_uuid
The UUID for the account's cell.
overridden
A pointer to a 32-bit set of flags identifying the local
overrides, if any, for the account login information.
[NOT APPLICABLE ON OPENVMS]
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_login_get_effective() routine returns effective login
information for the specified account. Login information is
extracted from the account's entry in the registry database.
Effective login information is the login information from the
registry database.
The overridden parameter indicates which, if any, of the following local
overrides have been defined for the account:
+ The UNIX user ID
+ The group ID
+ The encrypted password
+ The account's miscellaneous information (gecos) field
+ The account's home directory
+ The account's login shell
FILES
SYS$COMMON:[DCE$LIBRARY]MISC.IDL
The idl file from which dce/misc.h was derived.
ERRORS
sec_rgy__object_not_found
The specified account could not be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_add
sec_rgy_login_get_info
132 – sec_rgy_login_get_info
NAME
sec_rgy_login_get_info - Returns login information for an account
SYNOPSIS
#include <dce/misc.h>
void sec_rgy_login_get_info(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_key_t *key_parts,
sec_rgy_sid_t *sid,
sec_rgy_unix_sid_t *unix_sid,
sec_rgy_acct_user_t *user_part,
sec_rgy_acct_admin_t *admin_part,
sec_rgy_plcy_t *policy_data,
signed32 max_number,
signed32 *supplied_number,
uuid_t id_projlist[],
signed32 unix_projlist[],
signed32 *num_projects,
sec_rgy_name_t cell_name,
uuid_t *cell_uuid,
error_status_t *status);
PARAMETERS
Input
context
The registry server handle.
max_number
The maximum number of projects to be returned by the call. This
must be no larger than the allocated size of the projlist[]
arrays.
Input/Output
login_name
A pointer to the account login name. A login name is composed
of the names for the account's principal, group, and
organization (PGO) items.
Output
key_parts
A pointer to the minimum abbreviation allowed when logging in
to the account. Abbreviations are not currently implemented
and the only legal value is sec_rgy_acct_key_person.
sid A pointer to a sec_rgy_sid_t structure to receive the UUID's
representing the account's PGO items.
unix_sid
A pointer to a sec_rgy_unix_sid_t structure to receive the UNIX
numbers for the account's PGO items.
user_part
A pointer to a sec_rgy_acct_user_t structure to receive the
returned user data for the account.
admin_part
A pointer to a sec_rgy_acct_admin_t structure to receive the
returned administrative data for the account.
policy_data
A pointer to a sec_rgy_policy_t structure to receive the policy
data for the account. The policy data is associated with the
account's organization, as identified in the login name.
supplied_number
A pointer to the actual number of projects returned. This will
always be less than or equal to the max_number supplied on input.
id_projlist[]
An array to receive the UUID of each project returned. The size
allocated for the array is given by max_number. If this value
is less than the total number of projects in the account project
list, multiple calls must be made to return all of the projects.
unix_projlist[]
An array to receive the UNIX number of each project returned.
The size allocated for the array is given by max_number. If
this value is less than the total number of projects in the
account project list, multiple calls must be made to return
all of the projects.
num_projects
A pointer indicating the total number of projects in the
specified account's project list.
cell_name
The name of the account's cell.
cell_uuid
The UUID for the account's cell.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_login_get_info() routine returns login information for
the specified account. This information is extracted from the
account's entry in the registry database. To return any local over-
rides for the account's login data, use sec_rgy_login_get_effective().
Permissions Required
The sec_rgy_login_get_info() routine requires the r (read) permission
on the account principal from which the data is to be returned.
FILES
SYS$COMMON:[DCE$LIBRARY]MISC.IDL
The idl file from which dce/misc.h was derived.
ERRORS
sec_rgy_object_not_found
The specified account could not be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_add
sec_rgy_login_get_effective
133 – sec_rgy_pgo_add
NAME
sec_rgy_pgo_add - Adds a PGO item to the registry database
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_add(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
sec_rgy_pgo_item_t *pgo_item,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The valid
values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
name A pointer to a sec_rgy_name_t character string containing the
name of the new PGO item.
pgo_item
A pointer to a sec_rgy_pgo_item_t structure containing the data
for the new PGO item. The data in this structure includes the
PGO item's name, UUID, UNIX number (if any), and administrative
data, such as whether the item may have (or belong to) a
concurrent group set.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_add() routine adds a PGO item to the registry database.
The PGO data consists of the following:
+ The Universal Unique Identifier (UUID) of the PGO item. Specify
NULL to have the registry server create a new UUID for an item.
+ The UNIX number for the PGO item. If the registry uses embedded
UNIX IDs (where a subset of the UUID bits represent the UNIX ID),
then the specified ID must match the UUID, if both are specified.
Use a value of -1 for the UNIX number to match any value.
+ The quota for subaccounts allowed for this item entry.
+ The full name of the PGO item.
+ Flags (in the sec_rgy_pgo_flags_t format) indicating whether
- A principal item is an alias.
- The PGO item can be deleted from the registry.
- A principal item can have a concurrent group set.
- A group item can appear in a concurrent group set.
Permissions Required
The sec_rgy_pgo_add() routine requires the i (insert) permission on the
parent directory in which the the PGO item is to be created.
NOTES
An account can be added to the registry database only when all its
constituent PGO items are already in the database, and the appropriate
membership relationships between them are established. For example, to
establish an account with principal name tom, group name writers, and
organization name hp, all three names must exist as independent PGO
items in the database. Furthermore, tom must be a member of writers,
which must be a member of hp. (See sec_rgy_acct_add() to add an
account to the registry.)
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to add the specified
PGO item.
sec_rgy_object_exists
A PGO item already exists with the name given in name.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_delete
sec_rgy_pgo_rename
sec_rgy_pgo_replace
sec_rgy_acct_add
134 – sec_rgy_pgo_add_member
NAME
sec_rgy_pgo_add_member - Adds a person to a group or organization
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_add_member(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t go_name,
sec_rgy_name_t person_name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the person, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_group
The go_name parameter identifies a group.
sec_rgy_domain_org
The go_name parameter identifies an organization.
go_name
A character string (type sec_rgy_name_t) containing the name
of the group or organization to which the specified person will
be added.
person_name
A character string (type sec_rgy_name_t) containing the name
of the person to be added to the membership list of the group
or organization specified by go_name.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_add_member() routine adds a member to the membership
list of a group or organization in the registry database.
Permissions Required
The sec_rgy_pgo_add_member() routine requires the M (Member_list)
permission on the group or organization item specified by go_name.
If go_name specifies a group, the routine also requires the g
(groups) permission on the principal person_name.
NOTES
An account can be added to the registry database only when all its
constituent PGO items are already in the database, and the appropriate
membership relationships between them are established. For example, to
establish an account with person name tom, group name writers, and
organization name hp, all three names must exist as independent PGO
items in the database. Furthermore, tom must be a member of writers,
which must be a member of hp. (See the sec_rgy_acct_add() routine to
add an account to the registry.)
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to add members to the
specified group or organization.
sec_rgy_bad_domain
An invalid domain was specified. A member can be added
only to a group or organization, not a person.
sec_rgy_object_not_found
The registry server could not find the specified name.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_delete_member
sec_rgy_pgo_get_members
sec_rgy_pgo_is_member
135 – sec_rgy_pgo_delete
NAME
sec_rgy_pgo_delete - Deletes a PGO item from the registry database
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_delete(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
name A pointer to a sec_rgy_name_t character string containing the
name of the PGO item to be deleted.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_delete() routine deletes a PGO item from the registry
database. Any account depending on the deleted PGO item is also deleted.
Permissions Required
The sec_rgy_pgo_delete() routine requires the following permissions:
+ The d (delete) permission on the parent directory that contains
the the PGO item to be deleted.
+ The D (Delete_object) permission on the PGO item itself.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to delete the
specified item.
sec_rgy_object_not_found
The registry server could not find the specified item.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
136 – sec_rgy_pgo_delete_member
NAME
sec_rgy_pgo_delete_member - Deletes a member of a group or
organization
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_delete_member(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t go_name,
sec_rgy_name_t person_name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the person, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_group
The go_name parameter identifies a group.
sec_rgy_domain_org
The go_name parameter identifies an organization.
go_name
A character string (type sec_rgy_name_t) containing the name
of the group or organization from which the specified person
will be deleted.
person_name
A character string (type sec_rgy_name_t) containing the name
of the person to be deleted from the membership list of the
group or organization specified by go_name.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_delete_member() routine deletes a member from the
membership list of a group or organization. Any accounts in which
the person holds the deleted group or organization membership are
also deleted.
Permissions Required
The sec_rgy_pgo_delete_member() routine requires the M (Member_list)
permission on the group or organization item specified by go_name.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to delete the
specified member.
sec_rgy_bad_domain
An invalid domain was specified. Members can exist
only for groups and organizations, not for persons.
sec_rgy_object_not_found
The specified group or organization was not found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_add_member
137 – sec_rgy_pgo_get_by_eff_unix_num
NAME
sec_rgy_pgo_get_by_eff_unix_num - Returns the name and data for a
PGO item identified by its
effective UNIX number
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_get_by_eff_unix_num(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t scope,
signed32 unix_id,
boolean32 allow_aliases,
sec_rgy_cursor_t *item_cursor,
sec_rgy_pgo_item_t *pgo_item,
sec_rgy_name_t name,
boolean32 *overridden,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The UNIX number identifies a principal.
sec_rgy_domain_group
The UNIX number identifies a group.
Note that this function does not support the value sec_rgy_domain_org.
scope A character string (type sec_rgy_name_t) containing the scope
of the desired search. The registry database is designed to
accommodate a tree-structured name hierarchy. The scope of a
search is the name of the branch under which the search takes
place. For example, all names in a registry might start with
/alpha, and be divided further into /beta or /gamma. To search
only the part of the database under /beta, the scope of the
search would be /alpha/beta, and any resulting PGO items would
have names beginning with this string. Note that these naming
conventions need not have anything to do with group or
organization PGO item membership lists.
unix_id
The UNIX number of the desired registry PGO item.
allow_aliases
A boolean32 value indicating whether to search for a primary
PGO item, or whether the search can be satisfied with an alias.
If TRUE, the routine returns the next entry found for the PGO
item. If FALSE, the routine returns only the primary entry.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in the
registry database. The sec_rgy_pgo_get_next() routine returns
the PGO item indicated by item_cursor, and advances the cursor
to point to the next item in the database. When the end of the
list of entries is reached, the routine returns the value
sec_rgy_no_more_entries in the status parameter. Use
sec_rgy_cursor_reset() to reset the cursor.
Output
pgo_item
A pointer to a sec_rgy_pgo_item_t structure to receive the data
for the returned PGO item. The data in this structure includes
the PGO item's name, UUID, UNIX number (if any), and
administrative data, such as whether the item, if a principal,
may have a concurrent group set. The data is as it appears in
the registry, for that UNIX number.
name A pointer to a sec_rgy_name_t character string containing the
returned name for the PGO item.
overridden
A pointer to a boolean32 value indicating whether or not the
supplied UNIX number has an entry in the local override file
(passwd_override or group_override). [NOT APPLICABLE ON OPENVMS]
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_get_by_eff_unix_num() routine returns the name and
data for a PGO item. The desired item is identified by its type
(domain) and its UNIX number.
This routine is similar to the sec_rgy_pgo_get_by_unix_num() routine.
The difference between the routines is that on UNIX,
sec_rgy_pgo_get_by_eff_unix_num() first searches the local override
files for the respective name_domain for a match with the supplied
UNIX number. If an override match is found, and an account or group
name is found in that entry, then that name is used to obtain PGO
data from the registry and the value of the overridden parameter is
set to TRUE.
The item_cursor parameter specifies the starting point for the search
through the registry database. It provides an automatic place holder
in the database. The routine automatically updates this variable to
point to the next PGO item after the returned item. The returned
cursor location can be supplied on a subsequent database access call
that also uses a PGO item cursor.
Permissions Required
The sec_rgy_pgo_get_by_eff_unix_num() routine requires the r (read)
permission on the PGO item to be viewed.
CAUTIONS
There are several different types of cursors used in the registry
Application Programmer Interface (API). Some cursors point to PGO
items, others point to members in a membership list, and others point
to account data. Do not use a cursor for one sort of object in a call
expecting another sort of object. For example, you cannot use the same
cursor on a call to sec_rgy_acct_get_projlist() and
sec_rgy_pgo_get_next(). The behavior in this case is undefined.
Furthermore, cursors are specific to a server. A cursor pointing
into one replica of the registry database is useless as a pointer
into another replica.
Use sec_rgy_cursor_reset() to renew a cursor for use with another
call or for another server.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_no_more_entries
The cursor is at the end of the list of PGO items.
sec_rgy_object_not_found
The specified PGO item was not found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_get_next
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
sec_rgy_cursor_reset
138 – sec_rgy_pgo_get_by_id
NAME
sec_rgy_pgo_get_by_id - Returns the name and data for a PGO item
identified by its UUID
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_get_by_id(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t scope,
uuid_t *item_id,
boolean32 allow_aliases,
sec_rgy_cursor_t *item_cursor,
sec_rgy_pgo_item_t *pgo_item,
sec_rgy_name_t name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The UUID identifies a principal.
sec_rgy_domain_group
The UUID identifies a group.
sec_rgy_domain_org
The UUID identifies an organization.
scope A character string (type sec_rgy_name_t) containing the scope
of the desired search. The registry database is designed to
accommodate a tree-structured name hierarchy. The scope of a
search is the name of the branch under which the search takes
place. For example, all names in a registry might start with
/alpha, and be divided further into /beta or /gamma. To search
only the part of the database under /beta, the scope of the
search would be /alpha/beta, and any resulting PGO items would
have names beginning with this string. Note that these naming
conventions need not have anything to do with group or
organization PGO item membership lists.
item_id
A pointer to the uuid_t variable containing the UUID (Unique
Universal Identifier) of the desired PGO item.
allow_aliases
A boolean32 value indicating whether to search for a primary
PGO item, or whether the search can be satisfied with an alias.
If TRUE, the routine returns the next entry found for the PGO
item. If FALSE, the routine returns only the primary entry.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in the
registry database. The sec_rgy_pgo_get_by_id() routine returns
the PGO item indicated by item_cursor, and advances the cursor
to point to the next item in the database. When the end of the
list of entries is reached, the routine returns
sec_rgy_no_more_entries in the status parameter. Use
sec_rgy_cursor_reset() to reset the cursor.
Output
pgo_item
A pointer to a sec_rgy_pgo_item_t structure to receive the data
for the returned PGO item. The data in this structure includes
the PGO item's name, UUID, UNIX number (if any), and
administrative data, such as whether the item, if a principal,
may have a concurrent group set.
name A pointer to a sec_rgy_name_t character string containing the
returned name for the PGO item.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_get_by_id() routine returns the name and data for
a PGO item. The desired item is identified by its type (domain) and
its UUID.
The item_cursor parameter specifies the starting point for the search
through the registry database. It provides an automatic place holder
in the database. The routine automatically updates this variable to
point to the next PGO item after the returned item. The returned
cursor location can be supplied on a subsequent database access call
that also uses a PGO item cursor.
Permissions Required
The sec_rgy_pgo_get_by_id() routine requires the r (read) permission
on the PGO item to be viewed.
CAUTIONS
There are several different types of cursors used in the registry
Application Programmer Interface (API). Some cursors point to PGO
items, others point to members in a membership list, and others point
to account data. Do not use a cursor for one sort of object in a call
expecting another sort of object. For example, you cannot use the
same cursor on a call to sec_rgy_acct_get_projlist() and
sec_rgy_pgo_get_next(). The behavior in this case is undefined.
Furthermore, cursors are specific to a server. A cursor pointing
into one replica of the registry database is useless as a pointer
into another replica.
Use sec_rgy_cursor_reset() to renew a cursor for use with another
call or for another server.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_no_more_entries
The cursor is at the end of the list of PGO items.
sec_rgy_object_not_found
The specified PGO item was not found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_get_next
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
sec_rgy_cursor_reset
139 – sec_rgy_pgo_get_by_name
NAME
sec_rgy_pgo_get_by_name - Returns the data for a named PGO item
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_get_by_name(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t pgo_name,
sec_rgy_cursor_t *item_cursor,
sec_rgy_pgo_item_t *pgo_item,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
pgo_name
A character string (type sec_rgy_name_t) containing the name
of the principal, group, or organization to search for.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in the
registry database. The sec_rgy_pgo_get_by_name() routine
returns the PGO item indicated by item_cursor, and advances
the cursor to point to the next item in the database. When the
end of the list of entries is reached, the routine returns the
value sec_rgy_no_more_entries in the status parameter. Use
sec_rgy_cursor_reset() to reset the cursor.
Output
pgo_item
A pointer to a sec_rgy_pgo_item_t structure to receive the data
for the returned PGO item. The data in this structure includes
the PGO item's name, UUID, UNIX number (if any), and
administrative data, such as whether the item, if a principal,
may have a concurrent group set.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_get_by_name() routine returns the data for a named PGO
item from the registry database. The desired item is identified by
its type (name_domain) and name.
The item_cursor parameter specifies the starting point for the search
through the registry database. It provides an automatic place holder
in the database. The routine automatically updates this variable to
point to the next PGO item after the returned item. The returned
cursor location can be supplied on a subsequent database access call
that also uses a PGO item cursor.
Permissions Required
The sec_rgy_pgo_get_by_name() routine requires the r (read) permission
on the PGO item to be viewed.
CAUTIONS
There are several different types of cursors used in the registry
Application Programmer Interface (API). Some cursors point to PGO
items, others point to members in a membership list, and others point
to account data. Do not use a cursor for one sort of object in a call
expecting another sort of object. For example, you cannot use the
same cursor on a call to sec_rgy_acct_get_projlist() and
sec_rgy_pgo_get_next(). The behavior in this case is undefined.
Furthermore, cursors are specific to a server. A cursor pointing into
one replica of the registry database is useless as a pointer into
another replica.
Use sec_rgy_cursor_reset() to renew a cursor for use with another
call or for another server.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_no_more_entries
The cursor is at the end of the list of PGO items.
sec_rgy_object_not_found
The specified PGO item was not found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_get_next
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
sec_rgy_cursor_reset
140 – sec_rgy_pgo_get_by_unix_num
NAME
sec_rgy_pgo_get_by_unix_num - Returns the name and data for a PGO
item identified by its UNIX ID
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_get_by_unix_num(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t scope,
signed32 unix_id,
boolean32 allow_aliases,
sec_rgy_cursor_t *item_cursor,
sec_rgy_pgo_item_t *pgo_item,
sec_rgy_name_t name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The UNIX number identifies a principal.
sec_rgy_domain_group
The UNIX number identifies a group.
sec_rgy_domain_org
The UNIX number identifies an organization.
scope A character string (type sec_rgy_name_t) containing the scope
of the desired search. The registry database is designed to
accommodate a tree-structured name hierarchy. The scope of a
search is the name of the branch under which the search takes
place. For example, all names in a registry might start with
/alpha, and be divided further into /beta or /gamma. To search
only the part of the database under /beta, the scope of the
search would be /alpha/beta, and any resulting PGO items would
have names beginning with this string. Note that these naming
conventions need not have anything to do with group or
organization PGO item membership lists.
unix_id
The UNIX number of the desired registry PGO item.
allow_aliases
A boolean32 value indicating whether to search for a primary
PGO item, or whether the search can be satisfied with an alias.
If TRUE, the routine returns the next entry found for the PGO
item. If FALSE, the routine returns only the primary entry.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in the
registry database. The sec_rgy_pgo_get_by_unix_num() routine
returns the PGO item indicated by item_cursor, and advances
the cursor to point to the next item in the database. When
the end of the list of entries is reached, the routine returns
the value sec_rgy_no_more_entries in the status parameter.
Use sec_rgy_cursor_reset() to reset the cursor.
Output
pgo_item
A pointer to a sec_rgy_pgo_item_t structure to receive the data
for the returned PGO item. The data in this structure includes
the PGO item's name, UUID, UNIX number (if any), and
administrative data, such as whether the item, if a principal,
may have a concurrent group set.
name A pointer to a sec_rgy_name_t character string containing the
returned name for the PGO item.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_get_by_unix_num() routine returns the name and data
for a PGO item. The desired item is identified by its type (domain)
and its UNIX number.
The item_cursor parameter specifies the starting point for the search
through the registry database. It provides an automatic place holder
in the database. The routine automatically updates this variable to
point to the next PGO item after the returned item. The returned
cursor location can be supplied on a subsequent database access call
that also uses a PGO item cursor.
Permissions Required
The sec_rgy_pgo_get_by_unix_num() routine requires the r (read)
permission on the PGO item to be viewed.
CAUTIONS
There are several different types of cursors used in the registry
Application Programmer Interface (API). Some cursors point to PGO
items, others point to members in a membership list, and others point
to account data. Do not use a cursor for one sort of object in a call
expecting another sort of object. For example, you cannot use the
same cursor on a call to sec_rgy_acct_get_projlist() and
sec_rgy_pgo_get_next(). The behavior in this case is undefined.
Furthermore, cursors are specific to a server. A cursor pointing
into one replica of the registry database is useless as a pointer
into another replica.
Use sec_rgy_cursor_reset() to renew a cursor for use with another
call or for another server.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_no_more_entries
The cursor is at the end of the list of PGO items.
sec_rgy_object_not_found
The specified PGO item was not found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_next
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
sec_rgy_cursor_reset
141 – sec_rgy_pgo_get_members
NAME
sec_rgy_pgo_get_members - Returns the membership list for a specified
group or organization or returns the set of
groups in which the specified principal is
a member.
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_get_members(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t go_name,
sec_rgy_cursor_t *member_cursor,
signed32 max_members,
sec_rgy_member_t member_list[],
signed32 *number_supplied,
signed32 *number_members,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a secd server. Use sec_rgy_site_open()
to acquire a bound handle.
name_domain
This variable specifies whether go_name identifies a principal,
group, or organization. The valid values are as follows:
sec_rgy_domain_group
The go_name parameter identifies a group.
sec_rgy_domain_org
The go_name parameter identifies an organization.
sec_rgy_domain_person
The go_name parameter identifies an principal.
go_name
A character string (type sec_rgy_name_t) that contains the name
of a group, organization, or principal. If go_name is the name
of a group or organization, the call returns the group's or
organization's member list. If go_name is the name of a
principal, the call returns a list of all groups in which the
principal is a member. (Contrast this with the
sec_rgy_acct_get_proj call, which returns only those groups in
which the principal is a member and that have been marked to be
included in the principal's project list.)
max_members
A signed32 variable containing the allocated dimension of the
member_list[] array. This is the maximum number of members or
groups that can be returned by a single call.
Input/Output
member_cursor
An opaque pointer to a specific entry in the membership list
or list of groups. The returned list begins with the entry
specified by member_cursor. Upon return, the cursor points to
the next entry after the last one returned. If there are no
more entries, the routine returns the value
sec_rgy_no_more_entries in the status parameter. Use
sec_rgy_cursor_reset() to reset the cursor to the beginning
of the list.
Output
member_list[]
An array of character strings to receive the returned member
or group names. The size allocated for the array is given by
max_number. If this value is less than the total number of
members or group names, multiple calls must be made to return
all of the members or groups.
number_supplied
A pointer to a signed32 variable to receive the number of
members or groups actually returned in member_list[].
number_members
A pointer to a signed32 variable to receive the total number
of members or groups. If this number is greater than
number_supplied, multiple calls to sec_rgy_pgo_get_members()
are necessary. Use the member_cursor parameter to coordinate
successive calls.
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_get_members() routine returns a list of the members in
the specified group or organization, or a list of groups in which a
specified principal is a member.
The member_cursor parameter specifies the starting point for the search
through the registry database. It provides an automatic place holder
in the database. The routine automatically updates member_cursor to
point to the next member or group (if any) after the returned list. If
not all of the members or groups are returned, the updated cursor can
be supplied on successive calls to return the remainder of the list.
Permissions Required
The sec_rgy_pgo_get_members() routine requires the r (read) permission
on the group, organization, or principal object specified by go_name.
CAUTIONS
There are several different types of cursors used in the registry
Application Programmer Interface (API). Some cursors point to PGO
items, others point to members in a membership list, and others point
to account data. Do not use a cursor for one sort of object in a call
expecting another sort of object. For example, you cannot use the same
cursor on a call to sec_rgy_acct_get_projlist() and
sec_rgy_pgo_get_next(). The behavior in this case is undefined.
Furthermore, cursors are specific to a server. A cursor pointing into
one replica of the registry database is useless as a pointer into
another replica.
Use sec_rgy_cursor_reset() to renew a cursor for use with another call
or for another server.
RETURN VALUES
The routine returns:
+ The names of the groups or members in member_list[]
+ The number of members or groups returned by the call in
number_supplied
+ The total number of members in the group or organization, or the
total number of groups in which the principal is a member in
number_members
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_no_more_entries
The cursor points to the end of the membership list for
a group or organization or to the end of the list of
groups for a principal.
sec_rgy_object_not_found
The specified group, organization, or principal could
not be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add_member
sec_rgy_cursor_reset
sec_rgy_pgo_is_member
sec_rgy_acct_get_proj
142 – sec_rgy_pgo_get_next
NAME
sec_rgy_pgo_get_next - Returns the next PGO item in the registry
database
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_get_next(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t scope,
sec_rgy_cursor_t *item_cursor,
sec_rgy_pgo_item_t *pgo_item,
sec_rgy_name_t name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group,
or organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
Returns the next principal item.
sec_rgy_domain_group
Returns the next group item.
sec_rgy_domain_org
Returns the next organization item.
scope A character string (type sec_rgy_name_t) containing the scope
of the desired search. The registry database is designed to
accommodate a tree-structured name hierarchy. The scope of a
search is the name of the branch under which the search takes
place. For example, all names in a registry might start with
/alpha, and be divided further into /beta or /gamma. To search
only the part of the database under /beta, the scope of the
search would be /alpha/beta, and any resulting PGO items would
have names beginning with this string. Note that these naming
conventions need not have anything to do with group or
organization PGO item membership lists.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in the
registry database. The sec_rgy_pgo_get_next() routine returns
the PGO item indicated by item_cursor, and advances the cursor
to point to the next item in the database. When the end of the
list of entries is reached, the routine returns the value
sec_rgy_no_more_entries in the status parameter. Use
sec_rgy_cursor_reset() to reset the cursor.
Output
pgo_item
A pointer to a sec_rgy_pgo_item_t structure to receive the data
for the returned PGO item. The data in this structure includes
the PGO item's name, UUID, UNIX number (if any), and
administrative data, such as whether the item, if a principal,
may have a concurrent group set.
name A pointer to a sec_rgy_name_t character string containing the
name of the returned PGO item.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_get_next() routine returns the data and name for the
PGO in the registry database indicated by item_cursor. It also
advances the cursor to point to the next PGO item in the database.
Successive calls to this routine return all the PGO items in the
database of the specified type (given by name_domain), in storage order.
The PGO data consists of the following:
+ The Universal Unique Identifier (UUID) of the PGO item.
+ The UNIX number for the PGO item.
+ The quota for subaccounts.
+ The full name of the PGO item.
+ Flags indicating whether
- A principal item is an alias.
- The PGO item can be deleted.
- A principal item can have a concurrent group set.
- A group item can appear on a concurrent group set.
Permissions Required
The sec_rgy_pgo_get_next() routine requires the r (read) permission
on the PGO item to be viewed.
CAUTIONS
There are several different types of cursors used in the registry
Application Programmer Interface (API). Some cursors point to PGO
items, others point to members in a membership list, and others
point to account data. Do not use a cursor for one sort of object
in a call expecting another sort of object. For example, you cannot
use the same cursor on a call to sec_rgy_acct_get_projlist() and
sec_rgy_pgo_get_next(). The behavior in this case is undefined.
Furthermore, cursors are specific to a server. A cursor pointing
into one replica of the registry database is useless as a pointer
into another replica.
Use sec_rgy_cursor_reset() to renew a cursor for use with another
call or for another server.
RETURN VALUES
The routine returns the data for the returned PGO item in pgo_item
and the name in name.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_no_more_entries
The cursor is at the end of the list of PGO items.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_cursor_reset
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_unix_num_to_id
143 – sec_rgy_pgo_id_to_name
NAME
sec_rgy_pgo_id_to_name - Returns the name for a PGO item identified
by its UUID
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_id_to_name(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
uuid_t *item_id,
sec_rgy_name_t pgo_name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The item_id parameter identifies a principal.
sec_rgy_domain_group
The item_id parameter identifies a group.
sec_rgy_domain_org
The item_id parameter identifies an organization.
item_id
A pointer to the uuid_t variable containing the input UUID
(Unique Universal Identifier).
Output
pgo_name
A character string (type sec_rgy_name_t) containing the name
of the principal, group, or organization with the input UUID.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_id_to_name() routine returns the name of the PGO item
having the specified UUID.
Permissions Required
The sec_rgy_pgo_id_to_name() routine requires at least one permission
of any kind on the PGO item to be viewed.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_object_not_found
No item with the specified UUID could be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
144 – sec_rgy_pgo_id_to_unix_num
NAME
sec_rgy_pgo_id_to_unix_num - Returns the UNIX number for a PGO
item identified by its UUID
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_id_to_unix_num(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
uuid_t *item_id,
signed32 *item_unix_id,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The item_id parameter identifies a principal.
sec_rgy_domain_group
The item_id parameter identifies a group.
sec_rgy_domain_org
The item_id parameter identifies an organization.
item_id
A pointer to the uuid_t variable containing the input UUID
(Unique Universal Identifier).
Output
item_unix_id
A pointer to the signed32 variable to receive the returned UNIX
number for the PGO item.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_id_to_unix_num() routine returns the UNIX number
for the PGO item having the specified UUID.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_object_not_found
No item with the specified UUID could be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_name
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
145 – sec_rgy_pgo_is_member
NAME
sec_rgy_pgo_is_member - Checks group or organization membership
SYNOPSIS
#include <dce/pgo.h>
boolean32 sec_rgy_pgo_is_member(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t go_name,
sec_rgy_name_t person_name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_group
The go_name parameter identifies a group.
sec_rgy_domain_org
The go_name parameter identifies an organization.
go_name
A character string (type sec_rgy_name_t) containing the name
of the group or organization whose membership list is in
question.
person_name
A character string (type sec_rgy_name_t) containing the name
of the principal whose membership in the group or organization
specified by go_name is in question.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_is_member() routine tests whether the specified
principal is a member of the named group or organization.
Permissions Required
The sec_rgy_pgo_is_member() routine requires the t (test) permission
on the group or organization item specified by go_name.
RETURN VALUES
The routine returns TRUE if the principal is a member of the named
group or organization. If the principal is not a member, the routine
returns FALSE.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_object_not_found
The named group or organization was not found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add_member
sec_rgy_pgo_get_members
146 – sec_rgy_pgo_name_to_id
NAME
sec_rgy_pgo_name_to_id - Returns the UUID for a named PGO item
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_name_to_id(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t pgo_name,
uuid_t *item_id,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
pgo_name
A character string (type sec_rgy_name_t) containing the name
of the principal, group, or organization whose UUID is desired.
Output
item_id
A pointer to the uuid_t variable containing the UUID (Unique
Universal Identifier) of the resulting PGO item.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_name_to_id() routine returns the UUID associated
with the named PGO item.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_object_not_found
The specified PGO item could not be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_unix_num_to_id
147 – sec_rgy_pgo_name_to_unix_num
NAME
sec_rgy_pgo_name_to_unix_num - Returns the UNIX number for a PGO item
identified by its name
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_name_to_unix_num(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t pgo_name,
signed32 *item_unix_id,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
pgo_name
A character string containing the name of the PGO item in
question.
Output
item_unix_id
A pointer to the signed32 variable to receive the returned UNIX
number for the PGO item.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_name_to_unix_num() routine returns the UNIX number
for the PGO item having the specified name.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_object_not_found
No item with the specified UUID could be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_name
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
148 – sec_rgy_pgo_rename
NAME
sec_rgy_pgo_rename - Changes the name of a PGO item in the registry
database
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_rename(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t old_name,
sec_rgy_name_t new_name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
old_name
A pointer to a sec_rgy_name_t character string containing the
existing name of the PGO item.
new_name
A pointer to a sec_rgy_name_t character string containing the new
name for the PGO item.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_rename() routine renames a PGO item in the registry
database.
Permissions Required
If the sec_rgy_pgo_rename() routine is performing a rename within a
directory, it requires the n (name) permission on the old name of the
PGO item. If the routine is performing a move between directories, it
requires the following permissions:
+ The d (delete) permission on the parent directory that contains the
PGO item.
+ The n (name) permission on the old name of the PGO item.
+ The i (insert) permission on the parent directory in which the PGO
item is to be added under the new name.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to change the name
of the specified PGO item.
sec_rgy_object_not_found
The registry server could not find the specified PGO item.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_replace
149 – sec_rgy_pgo_replace
NAME
sec_rgy_pgo_replace - Replaces the data in an existing PGO item
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_replace(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t pgo_name,
sec_rgy_pgo_item_t *pgo_item,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
pgo_name
A character string (type sec_rgy_name_t) containing the name
of the principal, group, or organization whose data is to be
replaced.
pgo_item
A pointer to a sec_rgy_pgo_item_t structure containing the new
data for the PGO item. The data in this structure includes the
PGO item's name, UUID, UNIX number (if any), and administrative
data, such as whether the item, if a principal, may have a
concurrent group set.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_replace() routine replaces the data associated with
a PGO item in the registry database.
The UNIX ID and UUID of a PGO item cannot be replaced. To change the
UNIX ID or UUID, the existing PGO item must be deleted and a new PGO
item added in its place. The one exception to this rule is that the
UNIX ID can be replaced in the PGO item for a cell principal. The
reason for this exception is that the UUID for a cell principal does
not contain an embedded UNIX ID.
Permissions Required
The sec_rgy_pgo_replace() routine requires at least one of the
following permissions:
+ The m (mgmt_info) permission on the PGO item, if quota or flags
is being set.
+ The f (fullname) permission on the PGO item, if fullname is being
set.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to replace the
specified PGO item.
sec_rgy_object_not_found
No PGO item was found with the given name.
sec_rgy_unix_id_changed
The UNIX number of the PGO item was changed.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_delete
sec_rgy_pgo_rename
150 – sec_rgy_pgo_unix_num_to_id
NAME
sec_rgy_pgo_unix_num_to_id - Returns the UUID for a PGO item
identified by its UNIX number
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_unix_num_to_id(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
signed32 item_unix_id,
uuid_t *item_id,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The item_unix_id parameter identifies a principal.
sec_rgy_domain_group
The item_unix_id parameter identifies a group.
sec_rgy_domain_org
The item_unix_id parameter identifies an
organization.
item_unix_id
The signed32 variable containing the UNIX number for the PGO
item.
Output
item_id
A pointer to the uuid_t variable containing the UUID (Unique
Universal Identifier) of the resulting PGO item.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_unix_num_to_id() routine returns the Universal Unique
Identifier (UUID) for a PGO item that has the specified UNIX number.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_object_not_found
No item with the specified UNIX number could be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
151 – sec_rgy_pgo_unix_num_to_name
NAME
sec_rgy_pgo_unix_num_to_name - Returns the name for a PGO item
identified by its UNIX number
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_unix_num_to_name(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
signed32 item_unix_id,
sec_rgy_name_t pgo_name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
The type of the principal, group, or organization (PGO) item
identified by item_unix_id. Valid values are as follows:
sec_rgy_domain_person
The item_unix_id parameter identifies a principal.
sec_rgy_domain_group
The item_unix_id parameter identifies a group.
sec_rgy_domain_org
The item_unix_id parameter identifies an
organization.
item_unix_id
The signed32 variable containing the UNIX number for the PGO
item.
Output
pgo_name
A character string containing the name of the PGO item in
question.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_unix_num_to_name() routine returns the name for a PGO
item that has the specified UNIX number.
Permissions Required
The sec_rgy_pgo_unix_num_to_name() routine requires at least one
permission of any kind on the PGO item identified by item_unix_id.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_object_not_found
No item with the specified UNIX number could be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
152 – sec_rgy_plcy_get_effective
NAME
sec_rgy_plcy_get_effective - Returns the effective policy for an
organization
SYNOPSIS
#include <dce/policy.h>
void sec_rgy_plcy_get_effective(
sec_rgy_handle_t context,
sec_rgy_name_t organization,
sec_rgy_plcy_t *policy_data,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
organization
A character string (type sec_rgy_name_t) containing the name
of the organization for which the policy data is to be returned.
If this string is empty, the routine returns the registry's
policy data.
Output
policy_data
A pointer to the sec_rgy_plcy_t structure to receive the
authentication policy. This structure contains the minimum
length of a user's password, the lifetime of a password, the
expiration date of a password, the lifetime of the entire
account, and some flags describing limitations on the password
spelling.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_plcy_get_effective() routine returns the effective policy
for the specified organization.
The effective policy data is the most restrictive combination of the
registry and the organization policies.
The policy data consists of the following:
+ The password expiration date. This is the date on which account
passwords will expire.
+ The minimum length allowed for account passwords.
+ The period of time (life span) for which account passwords will be
valid.
+ The period of time (life span) for which accounts will be valid.
+ Flags indicating whether account passwords can consist entirely
of spaces or entirely of alphanumeric characters.
Permissions Required
The sec_rgy_plcy_get_effective() routine requires the r (read)
permission on the policy object from which the data is to be returned.
If an organization is specified, the routine also requires the r
(read) permission on the organization.
NOTES
If no organization is specified, the routine returns the registry's
policy data. To return the effective policy, an organization must be
specified. This is because the routine compares the registry's
policy data with that of the organization to determine which is more
restrictive.
FILES
SYS$COMMON:[DCE$LIBRARY]POLICY.IDL
The idl file from which dce/policy.h was derived.
ERRORS
sec_rgy_object_not_found
The registry server could not find the specified
organization.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_plcy_get_info
sec_rgy_plcy_set_info
153 – sec_rgy_plcy_get_info
NAME
sec_rgy_plcy_get_info - Returns the policy for an organization
SYNOPSIS
#include <dce/policy.h>
void sec_rgy_plcy_get_info(
sec_rgy_handle_t context,
sec_rgy_name_t organization,
sec_rgy_plcy_t *policy_data,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
organization
A character string (type sec_rgy_name_t) containing the name
of the organization for which the policy data is to be returned.
If this string is empty, the routine returns the registry's
policy data.
Output
policy_data
A pointer to the sec_rgy_plcy_t structure to receive the
authentication policy. This structure contains the minimum
length of a user's password, the lifetime of a password, the
expiration date of a password, the lifetime of the entire
account, and some flags describing limitations on the password
spelling.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_plcy_get_info() routine returns the policy data for the
specified organization. If no organization is specified, the
registry's policy data is returned.
The policy data consists of the following:
+ The password expiration date. This is the date on which account
passwords will expire.
+ The minimum length allowed for account passwords.
+ The period of time (life span) for which account passwords will be
valid.
+ The period of time (life span) for which accounts will be valid.
+ Flags indicating whether account passwords can consist entirely
of spaces or entirely of alphanumeric characters.
Permissions Required
The sec_rgy_plcy_get_info() routine requires the r (read) permission
on the policy object or organization from which the data is to be
returned.
NOTES
The returned policy may not be in effect if the overriding
registry authorization policy is more restrictive. (See the
sec_rgy_auth_plcy_get_effective() routine.)
FILES
SYS$COMMON:[DCE$LIBRARY]POLICY.IDL
The idl file from which dce/policy.h was derived.
ERRORS
sec_rgy_object_not_found
The registry server could not find the specified
organization.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_plcy_get_effective_info
sec_rgy_plcy_set_info
154 – sec_rgy_plcy_set_info
NAME
sec_rgy_plcy_set_info - Sets the policy for an organization
SYNOPSIS
#include <dce/policy.h>
void sec_rgy_plcy_set_info(
sec_rgy_handle_t context,
sec_rgy_name_t organization,
sec_rgy_plcy_t *policy_data,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
organization
A character string (type sec_rgy_name_t) containing the name
of the organization for which the policy data is to be returned.
If this string is empty, the routine sets the registry's policy
data.
policy_data
A pointer to the sec_rgy_plcy_t structure containing the
authentication policy. This structure contains the minimum
length of a user's password, the lifetime of a password, the
expiration date of a password, the lifetime of the entire
account, and some flags describing limitations on the password
spelling.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_plcy_set_info() routine sets the authentication policy
for a specified organization. If no organization is specified, the
registry's policy data is set.
Policy data can be returned or set for individual organizations and
for the registry as a whole.
Permissions Required
The sec_rgy_plcy_set_info() routine requires the m (mgmt_info)
permission on the policy object or organization for which the data
is to be set.
NOTES
The policy set on an account may be less restrictive than the policy
set for the registry as a whole. In this case, the changes in policy
have no effect, since the effective policy is the most restrictive
combination of the organization and registry authentication policies.
(See the sec_rgy_auth_plcy_get_effective() routine.)
FILES
SYS$COMMON:[DCE$LIBRARY]POLICY.IDL
The idl file from which dce/policy.h was derived.
ERRORS
sec_rgy_not_authorized
The user is not authorized to perform this operation.
sec_rgy_object_not_found
The registry server could not find the specified
organization.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_plcy_get_effective
sec_rgy_plcy_get_info
155 – sec_rgy_properties_get_info
NAME
sec_rgy_properties_get_info - Returns registry properties
SYNOPSIS
#include <dce/policy.h>
void sec_rgy_properties_get_info(
sec_rgy_handle_t context,
sec_rgy_properties_t *properties,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
Output
properties
A pointer to a sec_rgy_properties_t structure to receive the
returned property information. A registry's property information
contains information such as the default and minimum lifetime
and other restrictions on privilege attribute certificates, the
realm authentication name, and whether or not this replica of
the registry supports updates.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_properties_get_info() routine returns a list of the registry
properties.
The property information consists of the following:
read_version
A stamp specifying the earliest version of the registry server
software that can read from this registry.
write_version
A stamp specifying the earliest version of the registry server
software that can write to this registry.
minimum_ticket_lifetime
The minimum period of time for which an authentication ticket
remains valid.
default_certificate_lifetime
The default period of time for which an authentication
certificate (ticket-granting ticket) remains valid. A process
can request an authentication certificate with a longer
lifetime. Note that the maximum lifetime for an authentication
certificate cannot exceed the lifetime established by the
effective policy for the requesting account.
low_unix_id_person
The lowest UNIX ID that can be assigned to a principal in the
registry.
low_unix_id_group
The lowest UNIX ID that can be assigned to a group in the
registry.
low_unix_id_org
The lowest UNIX ID that can be assigned to an organization in
the registry.
max_unix_id
The maximum UNIX ID that can be used for any item in the
registry.
realm A character string naming the cell controlled by this registry.
realm_uuid
The UUID of the cell controlled by this registry.
flags Flags indicating whether
sec_rgy_prop_readonly
If TRUE, the registry database is read-only.
sec_rgy_prop_auth_cert_unbound
If TRUE, privilege attribute certificates can be
generated for use at any site.
sec_rgy_prop_shadow_password
If FALSE, passwords can be distributed over the
network. If this flag is TRUE, passwords will be
stripped from the returned data to the
sec_rgy_acct_lookup(), and other calls that return
an account's encoded password.
sec_rgy_prop_embedded_unix_id
All registry UUIDs contain embedded UNIX IDs. This
implies that the UNIX ID of any registry object
cannot be changed, since UUIDs are immutable.
Permissions Required
The sec_rgy_properties_get_info() routine requires the r (read)
permission on the policy object from which the property information
is to be returned.
FILES
SYS$COMMON:[DCE$LIBRARY]POLICY.IDL
The idl file from which dce/policy.h was derived.
ERRORS
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_properties_set_info
156 – sec_rgy_properties_set_info
NAME
sec_rgy_properties_set_info - Sets registry properties
SYNOPSIS
#include <dce/policy.h>
void sec_rgy_properties_set_info(
sec_rgy_handle_t context,
sec_rgy_properties_t *properties,
error_status_t *status);
PARAMETERS
Input
context
The registry server handle. An opaque handle bound to a
registry server. Use sec_rgy_site_open() to acquire a bound
handle.
properties
A pointer to a sec_rgy_properties_t structure containing the
registry property information to be set. A registry's property
information contains information such as the default and
minimum lifetime and other restrictions on privilege attribute
certificates, the realm authentication name, and whether or not
this replica of the registry supports updates.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_properties_set_info() routine sets the registry properties.
The property information consists of the following:
read_version
A stamp specifying the earliest version of the registry server
software that can read from this registry.
write_version
A stamp specifying the earliest version of the registry server
software that can write to this registry.
minimum_ticket_lifetime
The minimum period of time for which an authentication ticket
remains valid.
default_certificate_lifetime
The default period of time for which an authentication
certificate (ticket-granting ticket) remains valid. A process
can request an authentication certificate with a longer
lifetime. Note that the maximum lifetime for an authentication
certificate cannot exceed the lifetime established by the
effective policy for the requesting account.
low_unix_id_person
The lowest UNIX ID that can be assigned to a principal in the
registry.
low_unix_id_group
The lowest UNIX ID that can be assigned to a group in the
registry.
low_unix_id_org
The lowest UNIX ID that can be assigned to an organization in
the registry.
max_unix_id
The maximum UNIX ID that can be used for any item in the
registry.
realm A character string naming the cell controlled by this registry.
realm_uuid
The UUID of the cell controlled by this registry.
flags Flags indicating whether
sec_rgy_prop_readonly
If TRUE, the registry database is read-only.
sec_rgy_prop_auth_cert_unbound
If TRUE, privilege attribute certificates can be
generated for use at any site.
sec_rgy_prop_shadow_password
If FALSE, passwords can be distributed over the
network. If this flag is TRUE, passwords will be
stripped from the returned data to the
sec_rgy_acct_lookup(), and other calls that return
an account's encoded password.
sec_rgy_prop_embedded_unix_id
All registry UUIDs contain embedded UNIX IDs. This
implies that the UNIX ID of any registry object
cannot be changed, since UUIDs are immutable.
Permissions Required
The sec_rgy_properties_set_info() routine requires the m (mgmt_info)
permission on the policy object for which the property information is
to be set.
FILES
SYS$COMMON:[DCE$LIBRARY]POLICY.IDL
The idl file from which dce/policy.h was derived.
ERRORS
sec_rgy_not_authorized
The user is not authorized to change the registry
properties.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_properties_get_info
157 – sec_rgy_site_bind
NAME
sec_rgy_site_bind - Binds to a registry site
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_bind(
unsigned_char_t *site_name,
sec_rgy_bind_auth_info_t *auth_info,
sec_rgy_handle_t *context,
error_status_t *status);
PARAMETERS
Input
site_name
A character string (type unsigned_char_t) containing the name
of the registry site to bind to. Supply this name in any of
the following forms:
+ To randomly choose a site to bind to in the named cell,
specify a cell name (for example, /.../r_d.com or /.:
for the local cell)
+ To bind to a specific site in a specific cell, specify
either the site's global name (for example,
/.../r_d.com/subsys/dce/sec/rs_server_250_2) or the site's
network address (for example, ncadg_ip_udp:15.22.144.248)
auth_info
A pointer to the sec_rgy_bind_auth_info_t structure that
identifies the authentication protocol, protection level, and
authorization protocol to use in establishing the binding.
(See the rpc_binding_set_auth_info() routine). If the
sec_rgy_bind_auth_info_t structure specifies authenticated rpc,
the caller must have established a valid network identity for
this call to succeed.
Output
context
A pointer to a sec_rgy_handle_t variable. Upon return, this
contains a registry server handle indicating ("bound to") the
desired registry site.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_bind() call binds to a registry site at the security
level specified by the auth_info parameter. The site_name parameter
identifies the registry to use. If site_name is NULL, or a zero-
length string, a registry site in the local cell is selected by the
client agent.
NOTES
Like the sec_rgy_site_bind_query() routine, this routine binds
arbitrarily to either an update or query site. Although update
sites can accept queries, query sites cannot accept updates. To
specifically select an update site, use sec_rgy_site_bind_update().
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
sec_login_s_no_current_context
The caller does not have a valid network login context.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_open
sec_rgy_cell_bind
158 – sec_rgy_site_bind_query
NAME
sec_rgy_site_bind_query - Binds to a registry query site
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_bind_query(
unsigned_char_t *site_name,
sec_rgy_bind_auth_info_t *auth_info,
sec_rgy_handle_t *context,
error_status_t *status);
PARAMETERS
Input
site_name
A character string (type unsigned_char_t) containing the name
of the registry site to bind to. Supply this name in any of
the following forms:
+ To randomly choose a site to bind to in the named cell,
specify a cell name (for example, /.../r_d.com or /.:
for the local cell)
+ To bind to a specific site in a specific cell, specify
either the site's global name (for example,
/.../r_d.com/subsys/dce/sec/rs_server_250_2) or the site's
network address (for example, ncadg_ip_udp:15.22.144.248)
auth_info
A pointer to the sec_rgy_bind_auth_info_t structure that
identifies the authentication protocol, protection level, and
authorization protocol to use in establishing the binding.
(See the rpc_binding_set_auth_info() routine). If the
sec_rgy_bind_auth_info_t structure specifies authenticated rpc,
the caller must have established a valid network identity for
this call to succeed.
Output
context
A pointer to a sec_rgy_handle_t variable. Upon return, this
contains a registry server handle indicating ("bound to") the
desired registry site.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_bind_query() routine binds to a registry query site
at an arbitrary level of security. A registry query site is a satellite
server that operates on a periodically updated copy of the main
registry database. To change the registry database, it is necessary
to change a registry update site, which then automatically updates its
associated query sites. No changes can be made directly to a registry
query database.
The site_name parameter identifies the query site to use. If site_name
is NULL, or a zero-length string, a query site in the local cell is
selected by the client agent.
The handle for the associated registry server is returned in context.
NOTES
Like sec_rgy_bind_open() routine, this routine binds arbitrarily to
either an update or query site. Although update sites can accept
queries, query sites cannot accept updates. To specifically select
an update site, use sec_rgy_site_bind_update().
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
sec_login_s_no_current_context
The caller does not have a valid network login context.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_open
sec_rgy_site_bind
159 – sec_rgy_site_bind_update
NAME
sec_rgy_site_bind_update - Binds to a registry update site
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_bind_update(
unsigned_char_t *site_name,
sec_rgy_bind_auth_info_t *auth_info,
sec_rgy_handle_t *context,
error_status_t *status);
PARAMETERS
Input
site_name
A character string (type unsigned_char_t) containing the name
of the registry site to bind to. Supply this name in any of
the following forms:
+ To choose the update site to bind to in the named cell,
specify a cell name (for example, /.../r_d.com or /.:
for the local cell)
+ To start the search for the update site at a specific
replica in the replica's cell, specify either the
replica's global name (for example,
/.../r_d.com/subsys/dce/sec/rs_server_250_2) or the
replica's network address (for example,
ncadg_ip_udp:15.22.144.248)
auth_info
A pointer to the sec_rgy_bind_auth_info_t structure that
identifies the authentication protocol, protection level,
and authorization protocol to use in establishing the binding.
(See the rpc_binding_set_auth_info() routine). If the
sec_rgy_bind_auth_info_t structure specifies authenticated rpc,
the caller must have established a valid network identity for
this call to succeed.
Output
context
A pointer to a sec_rgy_handle_t variable. Upon return, this
contains a registry server handle indicating ("bound to") the
desired registry site.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_bind_update() routine binds to a registry update site.
A registry update site is a master server that may control several
satellite (query) servers. To change the registry database, it is
necessary to change a registry update site, which then automatically
updates its associated query sites. No changes can be made directly to
a registry query database.
The site_name parameter identifies either the cell in which to find
the update site or the replica at which to start the search for the
update site. If site_name is NULL, or a zero-length string, an update
site in the local cell is selected by the client agent.
The handle for the associated registry server is returned in context.
The handle is to an update site. Use this registry context handle in
subsequent calls that update or query the the registry database (for
example, the sec_rgy_pgo_add() or sec_rgy_acct_lookup() call).
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
sec_login_s_no_current_context
The caller does not have a valid network login context.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_open
sec_rgy_site_bind
sec_rgy_site_open
160 – sec_rgy_site_binding_get_info
NAME
sec_rgy_site_binding_get_info - Returns information from the registry
binding handle
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_binding_get_info(
sec_rgy_handle_t context,
unsigned_char_t **cell_name,
unsigned_char_t **server_name,
unsigned_char_t **string_binding,
sec_rgy_bind_auth_info_t *auth_info,
error_status_t *status);
PARAMETERS
Input
context
A sec_rgy_handle_t variable that contains a registry server
handle indicating ("bound to") the desired registry site. To
obtain information on the default binding handle, initialize
context to sec_rgy_default_handle. A valid login context must
be set for the process if context is set to
sec_rgy_default_handle; otherwise the error
sec_under_login_s_no_current_context is returned.
Output
cell_name
The name of the home cell for this registry.
server_name
The name of the node on which the server is resident. This name
is either a global name or a network address, depending on the
form in which the name was input to the call that bound to the
site.
string_binding
A string containing binding information from sec_rgy_handle_t.
auth_info
A pointer to the sec_rgy_bind_auth_info_t structure that
identifies the authentication protocol, protection level,
and authorization protocol to use in establishing the binding.
(See the rpc_binding_set_auth_info() routine).
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_binding_get_info() routine returns the site name and
authentication information associated with the context parameter. If
the context is the default context, the information for the default
binding is returned. Passing in a NULL value for any of the output
values (except for status) will prevent that value from being returned.
Memory is allocated for the string returned in the cell_name,
server_name, and string_binding parameters. The application calls the
rpc_string_free() routine to deallocate that memory.
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
sec_under_login_s_no_current_context
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_open
sec_rgy_site_bind
161 – sec_rgy_site_close
NAME
sec_rgy_site_close - Frees the binding handle for a registry server
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_close(
sec_rgy_handle_t context,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle indicating ("bound to") a registry server.
Use sec_rgy_site_open() to acquire a bound handle.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_close() routine frees the memory occupied by the
specified handle and destroys its binding with the registry server.
NOTES
A handle cannot be used after it is freed.
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_get
sec_rgy_site_is_readonly
sec_rgy_site_open
sec_rgy_site_open_query
sec_rgy_site_open_update
162 – sec_rgy_site_get
NAME
sec_rgy_site_get - Returns the string representation for a bound
registry site
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_get(
sec_rgy_handle_t context,
unsigned_char_t **site_name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle indicating (bound to'') a registry server.
Use sec_rgy_site_open() to acquire a bound handle. To obtain
information on the default binding handle, initialize context
to sec_rgy_default_handle. A valid login context must be set
for the process if context is set to sec_rgy_default_handle;
otherwise the error sec_under_login_s_no_current_context is
returned.
Output
site_name
A pointer to a character string (type unsigned_char_t)
containing the returned name of the registry site associated
with context, the given registry server handle.
The name is either a global name or a network address,
depending on the form in which the name was input to the call
that bound to the site.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_get() routine returns the name of the registry site
associated with the specified handle. If the handle is the default
context, the routine returns the name of the default context's site.
Memory is allocated for the string returned in the site_name
parameter. The application calls the rpc_string_free() routine to
deallocate that memory.
NOTES
To obtain binding information, the use of the
sec_rgy_site_binding_get_info() call is recommended in place of this
call.
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
sec_under_login_s_no_current_context
sec_rgy_server_unavailable
The requested registry server is not available.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_open
163 – sec_rgy_site_is_readonly
NAME
sec_rgy_site_is_readonly - Checks whether a registry site is read-only
SYNOPSIS
#include <dce/binding.h>
boolean32 sec_rgy_site_is_readonly(
sec_rgy_handle_t context);
PARAMETERS
Input
context
An opaque handle indicating (bound to'') a registry server.
Use sec_rgy_site_open() to acquire a bound handle.
DESCRIPTION
The sec_rgy_site_is_readonly() routine checks whether the registry
site associated with the specified handle is a query site or an
update site. A query site is a read-only replica of a master registry
database. The update site accepts changes to the registry database,
and duplicates the changes in its associated query sites.
RETURN VALUES
The routine returns:
+ TRUE if the registry site is read-only or if there was an error
using the specified handle
+ FALSE if the registry site is an update site
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_open
sec_rgy_site_open_query
164 – sec_rgy_site_open
NAME
sec_rgy_site_open - Binds to a registry site
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_open(
unsigned_char_t *site_name,
sec_rgy_handle_t *context,
error_status_t *status);
PARAMETERS
Input
site_name
A pointer to a character string (type unsigned_char_t)
containing the name of the registry site to bind to. Supply
this name in any of the following forms:
+ To randomly choose a site to bind to in the named cell,
specify a cell name (for example, /.../r_d.com or /.: for
the local cell)
+ To bind to a specific site in a specific cell, specify either
the site's global name (for example,
/.../r_d.com/subsys/dce/sec/rs_server_250_2) or the site's
network address (for example, ncadg_ip_udp:15.22.144.248)
Note that if you specify the name of a specific secd to bind to and
the name is not valid, the call will bind to a random site in the cell
if the specified cell name is valid.
Output
context
A pointer to a sec_rgy_handle_t variable. Upon return, this
contains a registry server handle indicating ("bound to") the
desired registry site.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_open() routine binds to a registry site at the level
of security specified in the rpc_binding_set_auth_info() call. The
site_name parameter identifies the registry to use. If site_name is
NULL, or a zero-length string, a registry site in the local cell is
selected by the client agent. The caller must have established a
valid network identity for this call to succeed.
NOTES
To bind to a registry site, the use of the sec_rgy_site_bind() call is
recommended in place of this call.
Like sec_rgy_site_open_query() routine, this routine binds arbitrarily
to either an update or query site. Although update sites can accept
queries, query sites cannot accept updates. To specifically select
an update site, use sec_rgy_site_open_update().
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
sec_login_s_no_current_context
The caller does not have a valid network login context.
sec_rgy_server_unavailable
The requested registry server is not available.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_close
sec_rgy_site_is_readonly
sec_rgy_site_open_query
sec_rgy_site_open_update
165 – sec_rgy_site_open_query
NAME
sec_rgy_site_open_query - Binds to a registry query site
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_open_query(
unsigned_char_t *site_name,
sec_rgy_handle_t *context,
error_status_t *status);
PARAMETERS
Input
site_name
A character string (type unsigned_char_t) containing the name
of the registry query site to bind to. Supply this name in any
of the following forms:
+ To randomly choose a site to bind to in the named cell,
specify a cell name (for example, /.../r_d.com or /.:
for the local cell)
+ To bind to a specific site in a specific cell, specify
either the site's global name (for example,
/.../r_d.com/subsys/dce/sec/rs_server_250_2) or the site's
network address (for example, ncadg_ip_udp:15.22.144.248)
Output
context
A pointer to a sec_rgy_handle_t variable. Upon return, this
contains a registry server handle indicating ("bound to") the
desired registry site.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_open_query() routine binds to a registry query site.
A registry query site is a satellite server that operates on a
periodically updated copy of the main registry database. To change
the registry database, it is necessary to change a registry update
site, which then automatically updates its associated query sites.
No changes can be made directly to a registry query database.
The site_name parameter identifies the query site to use. If site_name
is NULL, or a zero-length string, a query site in the local cell is
selected by the client agent.
The handle for the associated registry server is returned in context.
The caller must have established a valid network identity for this
call to succeed.
NOTES
To bind to a registry query site, the use of the
sec_rgy_site_bind_query() call is recommended in place of this call.
Like sec_rgy_site_open() routine, this routine binds arbitrarily to
either an update or query site. Although update sites can accept
queries, query sites cannot accept updates. To specifically select
an update site, use sec_rgy_site_open_update().
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
Errors
sec_login_s_no_current_context
The caller does not have a valid network login context.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_close
sec_rgy_site_get
sec_rgy_site_is_readonly
sec_rgy_site_open
sec_rgy_site_open_update
166 – sec_rgy_site_open_update
NAME
sec_rgy_site_open_update - Binds to a registry update site
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_open_update(
unsigned_char_t *site_name,
sec_rgy_handle_t *context,
error_status_t *status);
PARAMETERS
Input
site_name
A character string (type unsigned_char_t) containing the name
of an update registry site to bind to. Supply this name in
any of the following forms:
+ To choose the update site to bind to in the named cell,
specify a cell name (for example, /.../r_d.com or /.:
for the local cell)
+ To start the search for the update site at a specific
replica in the replica's cell, specify either the site's
global name (for example,
/.../r_d.com/subsys/dce/sec/rs_server_250_2) or the site's
network address (for example, ncadg_ip_udp:15.22.144.248)
Output
context
A pointer to a sec_rgy_handle_t variable. Upon return, this
contains a registry server handle indicating ("bound to") the
desired registry site.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_open_update() routine binds to a registry update site.
A registry update site is a master server that may control several
satellite (query) servers. To change the registry database, it is
necessary to change a registry update site, which then automatically
updates its associated query sites. No changes can be made directly to
a registry query database.
The site_name parameter identifies either the cell in which to find the
update site or the replica at which to start the search for the update
site. If site_name is NULL, or a zero-length string, an update site in
the local cell is selected by the client agent.
The handle for the associated registry server is returned in context.
The handle is to an update site. Use this registry context handle in
subsequent calls that update or query the the registry database (for
example, the sec_rgy_pgo_add() or sec_rgy_acct_lookup() call). The
caller must have established a valid network identity for this call to
succeed.
NOTES
To bind to a registry update site, the use of the
sec_rgy_site_bind_update() call is recommended in place of this call.
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
sec_login_s_no_current_context
The caller does not have a valid network login context.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_close
sec_rgy_site_get
sec_rgy_site_is_readonly
sec_rgy_site_open
sec_rgy_site_open_query
167 – sec_rgy_unix_getgrgid
NAME
sec_rgy_unix_getgrgid - Returns a UNIX style group entry for the
account matching the specified group ID
SYNOPSIS
#include <dce/rgynbase.h>
void sec_rgy_unix_getgrent(
sec_rgy_handle_t context,
signed32 gid,
signed32 max_number,
sec_rgy_cursor_t *item_cursor,
sec_rgy_unix_group_t *group_entry,
signed32 *number_members,
sec_rgy_member_t member_list[],
error_status_t *status);
PARAMETERS
Input
A pointer to an opaque handle bound to a registry server.
Use sec_rgy_site_open() to acquire a bound handle.
gid
A 32-bit integer specifying the group ID to match.
max_number
The maximum number of members to be returned by the call.
This must be no larger than the allocated size of the
member_list[] array.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in
the registry database. The sec_rgy_pgo_get_next() routine
returns the PGO item indicated by item_cursor, and advances
the cursor to point to the next item in the database. When
the end of the list of entries is reached, the routine
returns sec_rgy_no_more_entries. Use
sec_rgy_cursor_reset() to refresh the cursor.
Output
group_entry
A UNIX style group entry structure returned with
information about the account matching gid.
number_members
An signed 32-bit integer containing the total number of
member names returned in the member_list[] array.
member_list[]
An array of character strings to receive the returned
member names. The size allocated for the array is given by
max_number. If this value is less than the total number of
members in the membership list, multiple calls must be made
to return all of the members.
status
On successful completion, the routine returns
error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_rgy_unix_getgrgid() routine returns the next UNIX group
structure that matches the input UNIX group ID. The structure
is in the following form:
typedef struct {
sec_rgy_name_t name;
signed32 gid;
sec_rgy_member_buf_t members;
} sec_rgy_unix_group_t;
The structure includes
o The name of the group.
o The group's UNIX ID.
o A string containing the names of the group members. This
string is limited in size by the size of the
sec_rgy_member_buf_t
type defined in rgynbase.idl.
The routine also returns an array of member names, limited in size
by the number_members parameter.
This call is supplied in source code form.
FILES
SYS$COMMON:[DCE$LIBRARY]RGYBASE.IDL
The idl file from which dce/rgybase.h was derived.
ERRORS
sec_rgy_nomore_entries
The end of the list of entries has been reached.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro.
168 – sec_rgy_unix_getgrnam
NAME
sec_rgy_unix_getgrnam - Returns a UNIX style group entry for the
account matching the specified group name
SYNOPSIS
#include <dce/rgynbase.h>
void sec_rgy_unix_getgrnam(
sec_rgy_handle_t context,
sec_rgy_name_t name,
signed32 name_length,
signed32 max_num_members,
sec_rgy_cursor_t item_cursor,
sec_rgy_unix_group_t group_entry,
signed32 number_members,
sec_rgy_member_t member_list[],
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name A character string (of type sec_rgy_name_t) specifying the
group name to be matched.
name_length
An signed 32-bit integer specifying the length of name in
characters.
max_num_members
The maximum number of members to be returned by the call.
This must be no larger than the allocated size of the
member_list[] array.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in the
registry database. The sec_rgy_unix_getgrnam() routine returns
the PGO item indicated by item_cursor, and advances the cursor
to point to the next item in the database. When the end of the
list of entries is reached, the routine returns
sec_rgy_no_more_entries. Use sec_rgy_cursor_reset() to refresh
the cursor.
Output
group_entry
A UNIX style group entry structure returned with information
about the account matching name.
number_members
An signed 32-bit integer containing the total number of member
names returned in the member_list[] array.
member_list[]
An array of character strings to receive the returned member
names. The size allocated for the array is given by max_number.
If this value is less than the total number of members in the
membership list, multiple calls must be made to return all of
the members.
status
On successful completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The sec_rgy_unix_getgrnam() routine looks up the next group entry in
the registry that matches the input group name and returns the
corresponding UNIX style group structure. The structure is in the
following form:
typedef struct {
sec_rgy_name_t name;
signed32 gid;
sec_rgy_member_buf_t members;
} sec_rgy_unix_group_t;
The structure includes
+ The name of the group.
+ The group's UNIX ID.
+ A string containing the names of the group members. This string
is limited in size by the size of the sec_rgy_member_buf_t type
defined in rgynbase.idl.
The routine also returns an array of member names, limited in size
by the number_members parameter. Note that the array contains only
the names explicitly specified as members of the group. A principal
that was made a member of the group because that group was assigned
as the principal's primary group will not appear in the array.
This call is provided in source code form.
FILES
SYS$COMMON:[DCE$LIBRARY]RGYBASE.IDL
The idl file from which dce/rgybase.h was derived.
ERRORS
sec_rgy_no_more_entries
The end of the list of entries has been reached.
sec_rgy bad_data
The name supplied as input was too long.
error_status_ok
The call was successful.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
RELATED INFORMATION
Functions: sec_intro
169 – sec_rgy_unix_getpwnam
NAME
sec_rgy_unix_getpwnam - Returns a UNIX style passwd entry for account
matching the specified name.
SYNOPSIS
#include <dce/rgynbase.h>
void sec_rgy_unix_getpwnam (
sec_rgy_handle_t context,
sec_rgy_name_t name,
unsigned32 name_len,
sec_rgy_cursor_t *item_cursor,
sec_rgy_unix_passwd_t *passwd_entry,
error_status_t *status);
PARAMETERS
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name A character string (of type sec_rgy_name_t) containing the
name of the person, group, or organization whose name entry
is desired.
name_len A 32-bit integer representing the length of the name in
characters.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in
the registry database. The sec_rgy_unix_getpwnam routine
returns the PGO item indicated by item_cursor, and advances
the cursor to point to the next item in the database. When
the end of the list of entries is reached, the routine
returns sec_rgy_no_more_entries. Use sec_rgy_cursor_reset
to refresh the cursor.
Output
passwd_entry
A UNIX style passwd structure returned with information
about the account matching name.
status On successful completion, the routine returns
error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_rgy_unix_getpwnam routine returns the next UNIX passwd
structure that matches the input name. The structure is in the form:
typedef struct {
sec_rgy_unix_login_name_t name;
sec_rgy_unix_passwd_buf_t passwd;
signed32 uid;
signed32 gid;
signed32 oid;
sec_rgy_unix_gecos_t gecos;
sec_rgy_pname_t homedir;
sec_rgy_pname_t shell;
} sec_rgy_unix_passwd_t;
The structure includes:
+ The account's login name.
+ The account's password.
+ The account's UNIX ID.
+ The UNIX ID of group and organization associated with the
account.
+ The account's GECOS information.
+ The account's home directory.
+ The account's login shell
This call is provided in source code form.
FILES
SYS$COMMON:[DCE$LIBRARY]RGYNBASE.IDL
The idl file from which rgynbase.h was derived.
ERRORS
sec_rgy bad_data
The name supplied as input was too long.
error_status_ok
The call was successful.
sec_rgy_no_more_entries
The end of the list of entries has been reached.
RELATED INFORMATION
Functions: sec_intro
170 – sec_rgy_unix_getpwuid
NAME
sec_rgy_unix_getpwuid - Returns a UNIX style passwd entry for
the account matching the specified UID
SYNOPSIS
#include <dce/rgynbase.h>
void sec_rgy_unix_getpwuid(
sec_rgy_handle_t context,
signed32 uid,
sec_rgy_cursor_t *item_cursor,
sec_rgy_unix_passwd_t *passwd_entry,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
uid A 32-bit integer UNIX ID.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in the
registry database. The sec_rgy_unix_getpwuid() routine returns
the PGO item indicated by item_cursor, and advances the cursor
to point to the next item in the database. When the end of the
list of entries is reached, the routine returns
sec_rgy_no_more_entries. Use sec_rgy_cursor_reset() to refresh
the cursor.
Output
passwd_entry
A UNIX style password structure returned with information
about the account matching uid.
status
On successful completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The sec_rgy_unix_getpwuid() routine looks up the next passwd entry
in the registry that matches the input UNIX ID and returns the
corresponding sec_rgy_passwd structure. The structure is in the
following form:
typedef struct {
sec_rgy_unix_login_name_t name;
sec_rgy_unix_passwd_buf_t passwd;
signed32 Vuid;
signed32 Vgid;
signed32 oid;
sec_rgy_unix_gecos_t gecos;
sec_rgy_pname_t homedir;
sec_rgy_pname_t shell;
} sec_rgy_unix_passwd_t;
The structure includes
+ The account's login name.
+ The account's password.
+ The account's UNIX ID.
+ The UNIX ID of group and organization associated with the
account.
+ The account's GECOS information.
+ The account's home directory.
+ The account's login shell
FILES
SYS$COMMON:[DCE$LIBRARY]RGYNBASE.IDL
The idl file from which dce/rgynbase.h was derived.
This call is provided in source code form.
ERRORS
sec_rgy_no_more_entries
The end of the list of entries has been reached.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
171 – sec_rgy_wait_until_consistent
NAME
sec_rgy_wait_until_consistent - Blocks the caller while prior
updates are propagated to the
registry replicas
SYNOPSIS
#include <dce/misc.h>
boolean32 sec_rgy_wait_until_consistent(
sec_rgy_handle_t context,
error_status_t *status);
PARAMETERS
Input
context
The registry server handle associated with the master registry.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_wait_until_consistent() routine blocks callers until all
prior updates to the master registry have been propagated to all
active registry replicas.
RETURN VALUES
The routine returns TRUE when all active replicas have received the
prior updates. It returns FALSE if at least one replica did not
receive the updates.
FILES
SYS$COMMON:[DCE$LIBRARY]MISC.IDL
The idl file from which dce/misc.h was derived.
ERRORS
sec_rgy_server_unavailable
The server for the master registry is not available.
sec_rgy_read_only
Either the master site is in maintenance mode or the
site associated with the handle is a read-only (query)
site.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro