NAME
sec_intro - Application Program Interface to the DCE Security Service
DESCRIPTION
The Distributed Computing Environment (DCE) Security Service Application
Program Interface (API) allows developers to create network services with
complete access to all the authentication and authorization capabilities
of DCE Security Service and facilities.
The transaction of a network service generally consists of a client
process requesting some action from a server process. The client may
itself be a server, or a user, and the server may also be a client of
other servers. Before the targeted server executes the specified action,
it must be sure of the client's identity, and it must know whether the
client is authorized to request the service.
The Security Service API consists of the following sets of Remote
Procedure Calls (RPCs) used to communicate with various security-
related services and facilities:
+ rgy - Maintains the network registry of principal identities.
+ era - Maintains extended registry attributes.
+ login - Validates a principal's network identity and establish
delegated identities.
+ epa - Extracts privilege attributes from an opaque binding handle.
+ acl - Implements an Access Control List (ACL) protocol for the
authorization of a principal to network access and services.
+ key - Provides facilities for the maintenance of account keys for
daemon principals.
+ id - Maps file system names to Universal Unique IDs (UUIDs).
+ pwd_mgmt - Provides facilities for password management.
All the calls in this API have names beginning with the sec_ prefix.
These are the same calls used by various user-level tools provided as
part of the DCE. For example, the sec_create_db tool is written with
sec_rgy calls, acl_edit is written with sec_acl calls, and the login
program, with which a user logs in to a DCE system, is written using
sec_login calls. Most sites will find the user-level tools adequate
for their needs, and only must use the Security Service API to
customize or replace the functionality of these tools.
Though most of the calls in the Security Service API represent RPC
transactions, code has been provided on the client side to handle much
of the overhead involved with making remote calls. These "stubs" handle
binding to the requested security server site, the marshalling of data
into whatever form is needed for transmission, and other bookkeeping
involved with these remote calls. An application programmer can use
the Security Service interfaces as if they were composed of simple C
functions.
This reference page introduces each of the following APIs:
+ Registry APIs
+ Login APIs
+ Extended Privilege Attributes APIs
+ Extended Registry Attributes APIs
+ ACL APIs
+ Key Management APIs
+ ID Mapping APIs
+ Password Management APIs
The section for each API is organized as follows:
+ Synopsis
+ Data Types
+ Constants
+ Files
1 – REGISTRY_API_DATA_TYPES
SYNOPSIS
#include <dce/rgybase.h>
DATA TYPES
The following data types are used in sec_rgy_ calls:
sec_rgy_handle_t
A pointer to the registry server handle. The registry server is
bound to a handle with the sec_rgy_site_open() routine.
sec_rgy_bind_auth_info_type_t
A enumeration that defines whether or not the binding is
authenticated. This data type is used in conjunction with the
sec_rgy_bind_auth_info_t data type to set up the authorization
method and parameters for a binding. The
sec_rgy_bind_auth_info_type_t type consists of the following
elements:
+ sec_rgy_bind_auth_none-The binding is not authenticated.
+ sec_rgy_bind_auth_dce-The binding uses DCE shared-secret
key authentication.
sec_rgy_bind_auth_info_t
A discriminated union that defines authorization and authentication
parameters for a binding. This data type is used in conjunction
with the sec_rgy_bind_auth_info_type_t data type to set up the
authorization method and parameters for a binding. The
sec_rgy_bind_auth_info_t data type consists of the following
elements:
info_type A sec_rgy_bind_auth_info_type_t data type that specifies
whether or not the binding is authenticated. The contents of the
union depend on the value of sec_rgy_bind_auth_info_type_t.
For unauthenticated bindings
(sec_rgy_bind_auth_info_type_t = sec_rgy_bind_auth_none),
no parameters are supplied.
For authenticated bindings
(sec_rgy_bind_auth_info_type_t = sec_rgy_bind_auth_dce),
the dce_info structure is supplied.
dce_info A structure that consists of the following elements:
authn_level
An unsigned 32 bit integer indicating the
protection level for RPC calls made using the
server binding handle. The protection level
determines the degree to which authenticated
communications between the client and the
server are protected by the authentication
service specified by authn_svc. If the RPC
runtime or the RPC protocol in the bound
protocol sequence does not support a specified
level, the level is automatically upgraded to
the next higher supported level. The possible
protection levels are as follows:
+ rpc_c_protect_level_default - Uses the
default protection level for the specified
authentication service. The default
protection level for DCE shared-secret key
authentication is
rpc_c_protect_level_pkt_value
+ rpc_c_protect_level_none - Performs no
authentication: tickets are not exchanged,
session keys are not established, client
PACs or names are not certified, and trans-
missions are in the clear. Note that
although uncertified PACs should not be
trusted, they may be useful for debugging,
tracing, and measurement purposes.
+ rpc_c_protect_level_connect - Authenticates
only when the client establishes a rela-
tionship with the server.
+ rpc_c_protect_level_call - Authenticates
only at the beginning of each remote
procedure call when the server receives
the request. This level does not apply
to remote procedure calls made over a
connection-based protocol sequence (that
is, ncacn_ip_tcp). If this level is
specified and the binding handle uses a
connection-based protocol sequence, the
routine uses the rpc_c_protect_level_pkt
level instead.
+ rpc_c_protect_level_pkt - Ensures that
all data received is from the expected
client.
+ rpc_c_protect_level_pkt_integ - Ensures
and verifies that none of the data trans-
ferred between client and server has been
modified. This is the highest protection
level that is guaranteed to be present in
the RPC runtime.
+ rpc_c_protect_level_pkt_privacy -
Authenticates as specified by all of the
previous levels and also encrypts each
RPC argument value. This is the highest
protection level, but is not guaranteed
to be present in the RPC runtime.
authn_svc Specifies the authentication service to use.
The exact level of protection provided by the
authentication service is specified by
protect_level. The supported authentication
services are as follows:
+ rpc_c_authn_none - No authentication:
no tickets are exchanged, no session keys
established, client PACs or names are not
transmitted, and transmissions are in the
clear. Specify rpc_c_authn_none to turn
authentication off for remote procedure
calls made using this binding.
+ rpc_c_authn_dce_secret - DCE shared-secret
key authentication.
+ rpc_c_authn_default - Default authentica-
tion service. The current default authen-
tication service is DCE shared-secret key;
therefore, specifying rpc_c_authn_default
is equivalent to specifying
rpc_c_authn_dce_secret .
+ rpc_c_authn_dce_public - DCE public key
authentication (reserved for future use).
authz_svc Specifies the authorization service implemented
by the server for the interface. The validity
and trustworthiness of authorization data, like
any application data, is dependent on the
authentication service and protection level
specified. The supported authorization services
are as follows:
+ rpc_c_authz_none - Server performs no
authorization. This is valid only if
authn_svc is set to rpc_c_authn_none,
specifying that no authentication is
being performed.
+ rpc_c_authz_name - Server performs
authorization based on the client
principal name. This value cannot be
used if authn_svc is rpc_c_authn_none.
+ rpc_c_authz_dce - Server performs
authorization using the client's DCE
Privilege Attribute Certificate (PAC)
sent to the server with each remote
procedure call made with this binding.
Generally, access is checked against DCE
Access Control Lists (ACLs).
identity A value of type sec_login_handle_t that
represents a complete login context.
sec_timeval_sec_t
A 32-bit integer containing the seconds portion of a UNIX timeval_t,
to be used when expressing absolute dates.
sec_timeval_t
A structure containing the full UNIX time. The structure contains
two 32-bit integers that indicate seconds (sec) and microseconds
(usec) since 0:00, January 1, 1970.
sec_timeval_period_t
A 32-bit integer expressing seconds relative to some well-known
time.
sec_rgy_acct_key_t
Specifies how many parts (person, group, organization) of an account
login name will be enough to specify a unique abbreviation for that
account.
sec_rgy_cursor_t
A structure providing a pointer into a registry database. This type
is used for iterative operations on the registry information. For
example, a call to sec_rgy_pgo_get_members() might return the 10
account names following the input sec_rgy_cursor_t position. Upon
return, the cursor position will have been updated, so the next call
to that routine will return the next 10 names. The components of
this structure are not used by application programs.
sec_rgy_pname_t
A character string of length sec_rgy_pname_t_size.
sec_rgy_name_t
A character string of length sec_rgy_name_t_size.
sec_rgy_login_name_t
A structure representing an account login name. It contains three
strings of type sec_rgy_name_t:
pname The person name for the account.
gname The group name for the account.
oname The organization name for the account.
sec_rgy_member_t
A character string of length sec_rgy_name_t_size. LI
"sec_rgy_foreign_id_t" The representation of a foreign ID. This
structure contains two components:
cell A string of type uuid_t representing the UUID of the
foreign cell.
principal A string of type uuid_t representing the UUID of the
principal.
sec_rgy_sid_t
A structure identifying an account. It contains three fields:
person The UUID of the person part of the account.
group The UUID of the group part of the account.
org The UUID of the organization part of the account.
sec_rgy_unix_sid_t
A structure identifying an account with UNIX ID numbers. It
contains three fields:
person The UNIX ID of the person part of the account.
group The UNIX ID of the group part of the account.
org The UNIX ID of the organization part of the account.
sec_rgy_domain_t
This 32-bit integer specifies which naming domain a character string
refers to: person, group, or organization.
sec_rgy_pgo_flags_t
A 32-bit bitset containing flags pertaining to registry entries.
This type contains the following three flags:
sec_rgy_pgo_is_an_alias
If set, indicates the registry entry is an alias of
another entry.
sec_rgy_pgo_is_required
If set, the registry item is required and cannot be
deleted. An example of a required account is the one
for the registry server itself.
sec_rgy_pgo_projlist_ok
If the accompanying item is a person entry, this flag
indicates the person may have concurrent group sets.
If the item is a group entry, the flag means this group
can appear in a concurrent group set. The flag is
undefined for organization items.
sec_rgy_pgo_item_t
The structure identifying a registry item. It contains five com-
ponents:
id The UUID of the registry item, in uuid_t form.
unix_num A 32-bit integer containing the UNIX ID number of the
registry item.
quota A 32-bit integer representing the maximum number of user-
defined groups the account owner can create.
flags A sec_rgy_pgo_flags_t bitset containing information about
the entry.
fullname A sec_rgy_pname_t character string containing a full name
for the registry entry. For a person entry, this field
might contain the real name of the account owner. For a
group, it might contain a description of the group. This
is just a data field, and registry queries cannot search
on the fullname entry.
sec_rgy_acct_admin_flags_t
A 32-bit bitset containing administration flags used as part of the
administrator's information for any registry account. The set
contains three flags:
sec_rgy_acct_admin_valid
Specifies that the account is valid for login.
sec_rgy_acct_admin_server
If set, the account's name can be used as a server name in
a ticket-granting ticket.
sec_rgy_acct_admin_client
If set, the account's name can be used as a client name in
a ticket-granting ticket.
Note that you can prevent the principal from being authenticated, by
turning off both the sec_rgy_acct_admin_server and the
sec_rgy_acct_admin_client flags.
sec_rgy_acct_auth_flags_t
A 32-bit bitset containing account authorization flags used to
implement authentication policy as defined by the Kerberos Version
5 protocol. The set contains six flags:
sec_rgy_acct_auth_post_dated
Allows issuance of post-dated certificates.
sec_rgy_acct_auth_forwardable
Allows issuance of forwardable certificates.
sec_rgy_acct_auth_tgt
Allows issuance of certificates based on Ticket-Granting
Ticket (TGT) authentication. If this flag is not set, a
client requesting a service may have to supply a password
directly to the server.
sec_rgy_acct_auth_renewable
Allows issuance of renewable certificates.
sec_rgy_acct_auth_proxiable
Allows issuance of proxiable certificates.
sec_rgy_acct_auth_dup_session_key
Allows issuance of duplicate session keys.
sec_rgy_acct_admin_t
The portion of a registry account item containing components
relevant to administrators. This structure consists of the fields
listed below. Note that only expiration_date, good_since_date,
flags, and authentication_flags can be modified by an administrator;
the remaining fields are set by the Security server.
creator This field, in foreign_id_t format, identifies the
administrator who created the registry account.
creation_date
Specifies the creation date of the account, in
sec_timeval_sec_t format.
last_changer
Identifies the last person to change any of the account
information, in foreign_id_t format.
change_date
Specifies the date of the last modification of the account
information, in sec_timeval_sec_t format.
expiration_date
The date after which the account will no longer be valid.
In sec_timeval_sec_t format.
good_since_date
The Kerberos Version 5 TGT revocation date. TGTs issued
before this date will not be honored. In
sec_timeval_sec_t format.
flags Administrative flags in sec_rgy_acct_admin_flags_t format.
authentication_flags
Authentication flags in sec_rgy_acct_auth_flags_t format.
sec_rgy_acct_user_flags_t
A 32-bit bitset containing flags controlling user-modifiable
information. There is only one flag currently implemented. If
sec_rgy_acct_user_passwd_valid is set, it indicates the user pass-
word is valid. If it is not set, this flag prompts the user to
change the password on the next login attempt.
sec_rgy_acct_user_t
A structure containing registry account information. The structure
consists of the fields listed below. Note that only the gecos,
homedir, shell, and flags fields can be modified by the account
owner or other authorized useer; the remaining fields are set by
the Security server.
gecos This is a character string (in sec_rgy_pname_t format)
containing information about the account user. It
generally consists of everything after the full name in
the UNIX gecos format.
homedir The login directory for the account user, in
sec_rgy_pname_t format.
shell The default shell for the account user, in sec_rgy_pname_t
format.
passwd_version_number
An unsigned 32-bit integer, indicating the password
version number. This value is used as output only.
passwd The UNIX encrypted account password, in
sec_rgy_unix_passwd_buf_t format. This value is used as
output only.
passwd_dtm
The date the password was established, in
sec_timeval_sec_t format.
flags Account user flags, in sec_rgy_acct_user_flags_t format.
sec_rgy_plcy_pwd_flags_t
A 32-bit bitset containing two flags about password policy:
sec_rgy_plcy_pwd_no_spaces
If set, will not allow spaces in a password.
sec_rgy_plcy_pwd_non_alpha
If set, requires at least one nonalphanumeric character in
the password.
sec_rgy_plcy_t
A structure defining aspects of registry account policy. It
contains five components:
passwd_min_len
A 32-bit integer describing the minimum number of
characters in the account password.
passwd_lifetime
The number of seconds after a password's creation until it
expires, in sec_timeval_period_t format.
passwd_exp_date
The expiration date of the account password, in
sec_timeval_sec_t format.
acct_lifespan
The number of seconds after the creation of an account
before it expires, in sec_timeval_period_t format.
passwd_flags
Account password policy flags, in sec_rgy_plcy_pwd_flags_t
format.
sec_rgy_plcy_auth_t
This type describes authentication policy. It is a structure
containing two time periods, in sec_timeval_period_t format.
One, max_ticket_lifetime, specifies the maximum length of the
period during which a Ticket-Granting Ticket (TGT) will be valid.
The other, max_renewable_lifetime, specifies the maximum length of
time for which such a ticket may be renewed. This authentication
policy applies both to the registry as a whole as well as
individual accounts. The effective policy for a given account is
defined to bethe more restrictive of the site and principal authen-
tication policy.
sec_rgy_properties_t
A structure describing some registry properties. It contains the
following:
read_version
A 32-bit integer describing the earliest version of the
secd software that can read this registry.
write_version
A 32-bit integer describing the version of the secd soft-
ware that wrote this registry.
minimum_ticket_lifetime
The minimum lifetime of an authentication certificate, in
sec_timeval_period_t format.
default_certificate_lifetime
The "normal" lifetime of an an authentication certificate
(ticket-granting ticket in Kerberos parlance), in
sec_timeval_period_t format. Processes may request
authentication certificates with longer lifetimes up to,
but not in excess of, the maximum allowable lifetime as
determined by the effective policy for the account.
low_unix_id_person
The lowest UNIX number permissible for a person item in
the registry.
low_unix_id_group
The lowest UNIX number permissible for a group item in
the registry.
low_unix_id_org
The lowest UNIX number permissible for an organization
item in the registry.
max_unix_id
The largest UNIX number permissible for any registry
entry.
flags Property flags, in sec_rgy_properties_flags_t format.
realm The name of the cell, in sec_rgy_name_t form, for which
this registry is the authentication service.
realm_uuid
The UUID of the same cell.
sec_rgy_properties_flags_t
A 32-bit bitset, containing flags concerning registry properties:
sec_rgy_prop_readonly
If set (TRUE), indicates that this registry is a query
site.
sec_rgy_prop_auth_cert_unbound
If set (TRUE), the registry server will accept requests
from any site.
sec_rgy_prop_shadow_passwd
If the shadow password flag is set (TRUE), the registry
server will not include the account password when
responding to a request for the user data from a
specified account. This helps minimize the risk of an
account password being intercepted while traveling over
the network.
sec_rgy_prop_embedded_unix_id
Indicates that all UUIDs in this registry contain a UNIX
number embedded. This implies that the UNIX numbers of
objects in the registry cannot be changed, since UUIDs are
immutable.
sec_rgy_override_t
A 32-bit integer used as a flag for registry override mode.
Currently, its possible values are the constants
sec_rgy_no_override and sec_rgy_override. When this mode is
enabled, override data supplied by the node administrator will
replace some of the data gotten from the registry for a given
person/account under certain conditions. These conditions are
as follows:
1. The registry permits the requested overrides to be set for
this machine.
2. The override data is intended for person/account at hand.
When the mode is "override off," data from the registry is returned
to the end user or the application remains untouched.
sec_rgy_mode_resolve_t
A 32-bit integer used as a flag for resolve mode. Currently, its
possible values are the constants sec_rgy_no_resolve_pname and
sec_rgy_resolve_pname. When the mode is enabled, pathnames
containing leading // (slashes) will be translated into a form
understandable by the local machine's NFS.
sec_rgy_unix_passwd_buf_t
A character array of UNIX password strings.
CONSTANTS
The following constants are used in sec_rgy_ calls:
sec_rgy_default_handle
The value of an unbound registry server handle.
sec_rgy_acct_key_t Constants
The following 32-bit integer constants are used with the
sec_rgy_acct_key_t data type:
sec_rgy_acct_key_none
Invalid key.
sec_rgy_acct_key_person
The person name alone is enough.
sec_rgy_acct_key_group
The person and group names are both necessary for the account
abbreviation.
sec_rgy_acct_key_org
The person, group, and organization names are all necessary.
sec_rgy_acct_key_last
Key values must be less than this constant.
sec_rgy_pname_t_size
The maximum number of characters in a sec_rgy_pname_t.
sec_rgy_name_t_size
The maximum number of characters in a sec_rgy_name_t.
sec_rgy_domain_t Constants
The following 32-bit integer constants are the possible values of
the sec_rgy_domain_t data type:
sec_rgy_domain_person
The name in question refers to a person.
sec_rgy_domain_group
The name in question refers to a group.
sec_rgy_domain_org
The name in question refers to an organization.
sec_rgy_pgo_flags_t
A 32-bit constant equal to a variable of type sec_rgy_pgo_flags_t
with no flags set.
sec_rgy_quota_unlimited
A 32-bit integer. Set the quota field of the sec_rgy_pgo_item_t
type to this constant to override the registry quota limitation.
sec_rgy_acct_admin_flags_t
A 32-bit integer. This is the value of the
sec_rgy_acct_admin_flags_t bitset when none of its flags are set.
sec_rgy_acct_auth_flags_none
A 32-bit integer. This is the value of the
sec_rgy_acct_auth_flags_t bitset when none of its flags are set.
sec_rgy_acct_user_flags_t
A 16-bit integer. This is the value of the
sec_rgy_acct_user_flags_t bitset when none of its flags are set.
sec_rgy_plcy_pwd_flags_t
A 16-bit integer. This is the value of the
sec_rgy_policy_pwd_flags_t bitset when none of its flags are set.
sec_rgy_properties_flags_t
A 16-bit integer. This is the value of the
sec_rgy_properties_flags_t bitset when none of its flags are set.
sec_rgy_override
A 32-bit integer, which turns registry override mode on. When this
mode is enabled, override data supplied by the node administrator
will replace some of the data gotten from the registry for a given
person/account under certain conditions.
sec_rgy_no_override
A 32-bit integer, which turns off registry override mode.
sec_rgy_resolve_pname
A 32-bit integer, which turns on registry resolve mode. When the
mode is enabled, pathnames containing leading // (slashes) will be
translated into a form understandable by the local machine's NFS.
sec_rgy_no_resolve_pname
A 32-bit integer, which turns off registry resolve mode.
FILES
SYS$COMMON:[DCE$LIBRARY]RGYBASE.IDL
The idl file from which rgybase.h was derived.
2 – EXTENDED_REGISTRY_ATTRIBUTE_DATA_TYPES
SYNOPSIS
#include <dce/sec_attr_base.h>
DATA TYPES
The following data types are used in sec_rgy_attr calls:
sec_attr_twr_ref_t
A pointer to a tower. This data type is used with the
sec_attr_twr_set_t data type to allow a client to pass an
unallocated array of towers, which the server must allocate.
Both data types are used in conjunction with the
sec_attr_bind_type_t data type.
sec_attr_twr_set_t
A structure that defines an array of towers. This data type is used
with the sec_attr_twr_ref_t data type to allow a client to pass an
unallocated array of towers, which the server must allocate. Both
data types are used in conjunction with the sec_attr_bind_type_t
data type. The sec_attr_twr_set_t structure consists of the
following elements:
count An unsigned 32-bit integer specifying the number of towers
in the array.
towers[] An array of pointers (of type sec_attr_twr_ref_t) to
towers.
sec_attr_bind_type_t
A 32-bit integer that specifies the type of binding used by an
attribute interface. The data type (which is used in conjunction
with the sec_attr_binding_t data type) uses the following constants:
sec_attr_bind_type_string
An RPC string binding.
sec_attr_bind_type_twrs
A DCE protocol tower representation of a bindings.
sec_attr_bind_type_svrname
A name in rpc_c_ns_syntax format that identifies a CDS
entry containing the server's binding information. This
constant has the following structure:
name_syntax
Must be rpc_c_ns_syntax_dce to specify that DCE
naming rules are used to specify name.
name A pointer to a name of a CDS entry in
rpc_c_ns_syntax_dce syntax.
sec_attr_binding_t
A discriminated union that supplies information to generate a
binding handle for a attribute trigger. This data type, which is
used in conjunction with the sec_attr_bind_info_t data type, is
composed of the following elements:
bind_type A value of type sec_attr_bind_type_t that defines the type
of binding used by an attribute interface. The contents of
tagged union (below) depend on the value of
sec_attr_bind_type_t.
tagged_union
A tagged union specifying the binding handle. The
contents of the tagged union depend on the value of
bind_type as follows:
If bind_type is... Then tagged_union is...
_______________________________________________________________________
sec_attr_bind_type_string A pointer to an unsigned 32-bit character
string specifying an attribute's RPC string
binding.
_______________________________________________________________________
sec_attr_bind type_twrs An attribute's tower binding representation
of type sec_attr_twr_set_t.
_______________________________________________________________________
sec_attr_bind_svrname A pointer to a name of type
sec_attr_bind_type_t that specifies a
Cell Directory Service entry containing
an attribute trigger's binding information.
sec_attr_binding_p_t
A pointer to a sec_attr_binding_t union.
sec_attr_bind_auth_info_type_t
An enumeration that defines whether or not the binding is authenti-
cated. This data type is used in conjunction with the
sec_attr_bind_auth_info_t data type to set up the authorization
method and parameters for an RPC binding. The
sec_attr_bind_auth_info_type_t type consists of the following
elements:
+ sec_attr_bind_auth_none-The binding is not authenticated.
+ sec_attr_bind_auth_dce-The binding uses DCE shared-secret
key authentication.
sec_attr_bind_auth_info_t
A discriminated union that defines authorization and authentication
parameters for a binding. This data type is used in conjunction with
the sec_attr_bind_auth_info_type_t data type to set up the
authorization method and parameters for an RPC binding. The
sec_attr_bind_auth_info_t data type consists of the following
elements:
info_type A sec_attr_bind_auth_info_type_t data type that specifies
whether or not the binding is authenticated. The contents
of tagged union (below) depend on the value of
sec_attr_bind_auth_info_type_t.
tagged_union
A tagged union specifying the method of authorization and
the authorization parameters. For unauthenticated bindings
(sec_attr_bind_auth_info_type_t = sec_attr_bind_auth_none)
no parameters are supplied. For authenticated bindings
(sec_attr_bind_auth_info_type_t = sec_attr_bind_auth_dce),
the following union is supplied:
svr_princ_name
A pointer to a character string that specifies
the principal name of the server referenced by
the binding handle.
protect_level
An unsigned 32 bit integer indicating the
protection level for RPC calls made using the
server binding handle. The protection level
determines the degree to which authenticated
communications between the client and the
server are protected by the authentication
service specified by authn_svc.
If the RPC runtime or the RPC protocol in the
bound protocol sequence does not support a
specified level, the level is automatically
upgraded to the next higher supported level.
The possible protection levels are as follows:
+ rpc_c_protect_level_default - Uses the
default protection level for the specified
authentication service. The default
protection level for DCE shared-secret
key authentication is
rpc_c_protect_level_pkt_value
+ rpc_c_protect_level_none - Performs no
authentication: tickets are not exchanged,
session keys are not established, client
PACs or names are not certified, and
transmissions are in the clear. Note that
although uncertified PACs should not be
trusted, they may be useful for debugging,
tracing, and measurement purposes.
+ rpc_c_protect_level_connect - Authenticates
only when the client establishes a
relationship with the server.
+ rpc_c_protect_level_call - Authenticates
only at the beginning of each remote
procedure call when the server receives
the request. This level does not apply
to remote procedure calls made over a
connection-based protocol sequence (that
is, ncacn_ip_tcp). If this level is
specified and the binding handle uses a
connection-based protocol sequence, the
routine uses the rpc_c_protect_level_pkt
level instead.
+ rpc_c_protect_level_pkt - Ensures that all
data received is from the expected client.
+ rpc_c_protect_level_pkt_integ - Ensures
and verifies that none of the data trans-
ferred between client and server has been
modified. This is the highest protection
level that is guaranteed to be present in
the RPC runtime.
+ rpc_c_protect_level_pkt_privacy -
Authenticates as specified by all of the
previous levels and also encrypts each
RPC argument value. This is the highest
protection level, but is not guaranteed
to be present in the RPC runtime.
authn_svc Specifies the authentication service to use.
The exact level of protection provided by the
authentication service is specified by
protect_level. The supported authentication
services are as follows:
+ rpc_c_authn_none - No authentication:
no tickets are exchanged, no session keys
established, client PACs or names are not
transmitted, and transmissions are in the
clear. Specify rpc_c_authn_none to turn
authentication off for remote procedure
calls made using this binding.
+ rpc_c_authn_dce_secret - DCE shared-secret
key authentication.
+ rpc_c_authn_default - Default authentica-
tion service. The current default authen-
tication service is DCE shared-secret key;
therefore, specifying rpc_c_authn_default
is equivalent to specifying
rpc_c_authn_dce_secret.
+ rpc_c_authn_dce_public - DCE public key
authentication (reserved for future use).
authz_svc Specifies the authorization service implemented
by the server for the interface. The validity
and trustworthiness of authorization data, like
any application data, is dependent on the
authentication service and protection level
specified. The supported authorization services
are as follows:
+ rpc_c_authz_none - Server performs no
authorization. This is valid only if
authn_svc is set to rpc_c_authn_none,
specifying that no authentication is
being performed.
+ rpc_c_authz_name - Server performs
authorization based on the client
principal name. This value cannot be
used if authn_svc is rpc_c_authn_none.
+ rpc_c_authz_dce - Server performs
authorization using the client's DCE
Privilege Attribute Certificate (PAC)
sent to the server with each remote
procedure call made with this binding.
Generally, access is checked against DCE
Access Control Lists (ACLs).
sec_attr_bind_info_t
A structure that specifies attribute trigger binding information.
This data type, which is used in conjunction with the
sec_attr_schema_entry_t data type, contains of the following
elements:
auth_info The binding authorization information of type
sec_attr_bind_auth_info_t.
num_bindings
An unsigned 32-bit integer specifying the number of
binding handles in bindings.
bindings An array of sec_attr_binding_t data types that specify
binding handles.
sec_attr_bind_info_p_t
A pointer to a sec_attr_bind_info_t union.
sec_attr_encoding_t
An enumerator that contains attribute encoding tags used to define
the legal encodings for attribute values. The data type, which is
used in conjunction with the sec_attr_value_t and
sec_attr_schema_entry_t data types, consists of the following
elements:
sec_attr_enc_any
The attribute value can be of any legal encoding type.
This encoding tag is legal only in a schema entry. An
attribute entry must contain a concrete encoding type.
sec_attr_enc_void
The attribute has no value. It is simple a marker that is
either present or absent.
sec_attr_enc_printstring
The attribute value is a printable IDL string in DCE
Portable Character Set.
sec_attr_enc_printstring_array
The attribute value is an array of printstrings.
sec_attr_enc_integer
The attribute value is a signed 32-bit integer.
sec_attr_enc_bytes
The attribute value is a string of bytes. The string is
assumed to be a pickle or some other self describing type.
(See also the sec_attr_enc_bytes_t data type.)
sec_attr_enc_confidential_bytes
The attribute value is a string of bytes that have been
encrypted in the key of the principal object to which the
attribute is attached. The string is assumed to be a
pickle or some other self describing type. This encoding
type is useful only when attached to a principal object,
where it is decrypted and encrypted each time the
principal's password changes. (See also the
sec_attr_enc_bytes_t data type.)
sec_attr_enc_i18n_data
The attribute value is an "internationalized" string of
bytes with a tag identifying the OSF registered codeset
used to encode the data. (See also the
sec_attr_i18n_data_t data type.)
sec_attr_enc_uuid
The attribute is a value of type uuid_t, a DCE UUID.
sec_attr_enc_attr_set
The attribute value is an attribute set, a vector of
attribute UUIDs used to associate multiple related
attribute instances which are members of the set.
(See also the sec_attr_enc_attr_set_t data type.)
sec_attr_enc_binding
The attribute value is a sec_attr_bind_info_t data type
that specifies DCE server binding information.
sec_attr_enc_trig_binding
This encoding type is returned by rs_attr_lookup call. It
informs the client agent of the trigger binding informa-
tion of an attribute with a query trigger.
Unless sec_attr_enc_void or sec_attr_enc_any is specified, the attribute
values must conform to the attribute's encoding type.
sec_attr_enc_bytes_t
A structure that defines the length of attribute encoding values for
attributes encoded as sec_attr_enc_bytes and
sec_attr_enc_confidential_bytes. The structure, which is used in
conjunction with the sec_attr_value_t data type, consists of:
An unsigned 32-bit integer that defines the data length.
data[] An array of bytes specifying the length of attribute
encoding data.
sec_attr_i18n_data_t
A structure that defines the codeset used for attributes encoded as
sec_attr_enc_il8n_data and the length of the attribute encoding
values. The structure, which is used in conjunction with the
sec_attr_value_t data type, consists of:
An unsigned 32-bit identifier of a codeset registered with
the Open Software Foundation.
An unsigned 32-bit integer that defines the data length.
data[] An array of bytes specifying the length of attribute
encoding data.
sec_attr_enc_attr_set_t
A structure that that supplies the UUIDs of each member of an
attribute set. The structure, which is used in conjunction with
the sec_attr_value_t data type, consists of:
num_members
An unsigned 32-bit integer specifying the total number of
attribute's in the set.
members[] An array containing values of type uuid_t, the UUID of
each member in the set.
sec_attr_enc_printstring_t
A structure that contains a printstring.
sec_attr_enc_printstring_p_t
A pointer to a sec_attr_enc_printstring_t structure.
sec_attr_enc_str_array_t
A structure that defines a printstring array. It consists of:
num_strings
An unsigned 32-bit integer specifying the number of
strings in the array.
strings[] An array of pointers (of type
sec_attr_enc_print_string_p_t) to printstrings.
sec_attr_value_t
A discriminated union that defines attribute values. The union,
which is used in conjunction with the sec_attr_t data type,
consists of the following elements:
attr_encoding
A sec_attr_encoding_t data type that defines attribute
encoding. The contents of tagged union (below) depend
on the value of sec_attr_encoding_t.
tagged_union
A tagged union whose contents depend on attr_encoding as
follows:
If attr_encoding is... Then tagged_union is...
_______________________________________________________________________
sec_attr_enc_void NULL
_______________________________________________________________________
sec_attr_enc_printstring A pointer to printstring
_______________________________________________________________________
sec_attr_enc_printstring_array A pointer to an array of
printstrings
_______________________________________________________________________
sec_attr_enc_integer signed_int, a 32-bit signed integer
_______________________________________________________________________
sec_attr_enc_bytes bytes, a pointer to a structure of
type sec_attr_enc_bytes_t
_______________________________________________________________________
sec_attr_enc_confidential_bytes bytes, a pointer to a structure of
type sec_attr_enc_bytes_t
_______________________________________________________________________
sec_attr_enc_i18n_data idata, a pointer to a structure of
type sec_attr_i18n_data_t
_______________________________________________________________________
sec_attr_end_uuid uuid, a value of type uuid_t
_______________________________________________________________________
sec_attr_enc_attr_set attr_set, a pointer to a structure of
type sec_attr_enc_attr_set_t
_______________________________________________________________________
sec_attr_enc_binding binding, a pointer to a structure of
type sec_attr_binding_info_t
sec_attr_t
A structure that defines an attribute. The structure consists of:
attr_id A value of type uuid_t, the UUID of the attribute.
attr_value
A value of type sec_attr_value_t.
sec_attr_acl_mgr_info_t
A structure that contains the access control information defined in
a schema entry for an attribute. The structure, which is used in
conjunction with the sec_attr_schema_entry_t data type, consists of
the following elements:
acl_mgr_type
The value of type uuid_t that specifies the UUID of the
ACL manager type that supports the object type to which
the attribute can be attached. This field provides a
well-defined context for evaluating the permission bits
needed to operate on the attribute. The following table
lists the ACL Manager types for registry objects.
Registry Object ACL Manager Type Valid
Type Permissions
____________________________________________________________________
principal 06ab9320-0191-11ca-a9e8-08001e039d7d rcDnfmaug
____________________________________________________________________
group 06ab9640-0191-11ca-a9e8-08001e039d7d rctDnfmM
____________________________________________________________________
organization 06ab9960-0191-11ca-a9e8-08001e039d7d rctDnfmM
____________________________________________________________________
directory 06ab9c80-0191-11ca-a9e8-08001e039d7d rcidDn
____________________________________________________________________
policy 06ab8f10-0191-11ca-a9e8-08001e039d7d rcma
____________________________________________________________________
replist 2ac24970-60c3-11cb-b261-08001e039d7d cidmAI
query_permset
Data of type sec_acl_permset_t that defines the permission
bits needed to access the attribute's value.
update_permset
Data of type sec_acl_permset_t that defines the permission
bits needed to update the attribute's value.
test_permset
Data of type sec_acl_permset_t that defines the permission
bits needed to test the attribute's value.
delete_permset
Data of type sec_acl_permset_t that defines the permission
bits needed to delete an attribute instance.
sec_attr_acl_mgr_info_p_t
A pointer to a sec_attr_acl_mgr_info_t structure.
sec_attr_acl_mgr_info_set_t
A structure that defines an attribute's ACL manager set. The
structure consists of the following elements:
num_acl_mgrs
An unsigned 32-bit integer that specifies the number of
ACL managers in the ACL manager set.
mgr_info[]
An array of pointers of type sec_attr_mgr_info_p_t that
define the ACL manager types in the ACL manager set and
the permission sets associated with the ACL manager type.
sec_attr_intercell_action_t
An enumerator that specifies the action that should be taken by the
Privilege Service when it reads acceptable attributes from a foreign
cell. A foreign attribute is acceptable only if there is either a
schema entry for the foreign cell or if
sec_attr_intercell_act_accept is set to true.
This enumerator, which is used in conjunction with the
sec_attr_schema_entry_t data type, is composed of the following ele-
ments:
sec_attr_intercell_act_accept
If the unique flag in the sec_attr_schema_entry_t data
type is not set on, retain the attribute. If the unique
flag is set on, retain the attribute only if its value
is unique among all attribute instances of the same
attribute type within the cell.
sec_attr_intercell_act_reject
Discard the input attribute.
sec_attr_intercell_act_evaluate
Use the binding information in the trig_binding field of
this sec_attr_schema_entry_t data type to make a
sec_attr_trig_query call to a trigger server. That server
determines whether to retain the attribute value, discard
the attribute value, or map the attribute to another
value(s).
sec_attr_trig_type_t
Specifies the trigger type, a flag that determines whether an
attribute trigger should be invoked for query operations. The
data type, which is used in conjunction with the
sec_attr_schema_entry_t data type, uses the following constants:
The attribute trigger server is invoked for query opera-
tions.
sec_attr_trig_type_query
The attribute trigger server is invoked for update opera-
tions.
sec_attr_schema_entry_t
A structure that defines a complete attribute entry for the schema
catalog. The entry is identified by both a unique string name and a
unique attribute UUID. Although either can either can be used as a
retrieval key, the string name should be used for interactive access
to the attribute and the UUID for programmatic access. The attribute
UUID is used to identify the semantics defined for the attribute
type in the schema.
The sec_attr_schema_entry_t data type consists of the following ele-
ments:
attr_name A pointer to the attribute name.
attr_id A value of type uuid_t that identifies the attribute type.
attr_encoding
An enumerator of type sec_attr_encoding_t that specifies
the attribute's encoding.
acl_mgr_set
A structure of type sec_attr_acl_mgr_info_set_t that
specifies the ACL manager types that support the objects
on which attributes of this type can be created and the
permission bits supported by that ACL manager type.
schema_entry_flags
An unsigned integer of type sec_attr_sch_entry_flags_t
that defines bitsets for the following flags:
unique When set on, this flag indicates that each
instance of this attribute type must have a
unique value within the cell for the object
type implied by the ACL Manager type. If this
flag is not set on, uniqueness checks are not
performed for attribute writes.
multi_valued
When set on, this flag indicates that this
attribute type may be multi-valued; in other
words, multiple instances of the same
attribute type can be attached to a single
registry object. If this flag is not set on,
only one instance of this attribute type can
be attached to an object.
reserved When set on, this flag prevents the schema entry
from being deleted through any interface or by
any user. If this flag is not set on, the
entry can be deleted by any authorized
principal.
use_defaults
When set on, the system-defined default
attribute value will be returned on a client
query if an instance of this attribute does
not exist on the queried object. If this
flag is not set on, system defaults are not
used.
intercell_action
An enumerator of type sec_attr_intercell_action_t that
specifies how the Privilege Service will handle
attributes from a foreign cell.
trig_types
A flag of type sec_attr_trig_type_t that specifies whether
whether a trigger can perform update or query operations.
trig_binding
A pointer to a structure of type sec_attr_bind_info_t that
supplies the attribute trigger binding handle.
scope A pointer to a string that defines the objects to which
the attribute can be attached.
comment A pointer to a string that contains general comments about
the attribute.
sec_attr_schema_entry_parts_t
A 32-bit bitset containing flags that specify the schema entry
fields that can be modified on a schema entry update operation.
This data type contains the following flags:
sec_attr_schema_part_name
If set, indicates that the attribute name (attr_name) can
be changed.
sec_attr_schema_part_reserved
If set, indicates that the setting of the flag that deter-
mines whether or not the schema entry can be deleted
(reserved) can be changed.
sec_attr_schema_part_defaults
If set, indicates that the flag that determines whether or
not a query for a non-existent attribute will not result
in a search for a system default (apply_default) can be
changed.
sec_attr_schema_part_trig_bind
If set, indicates that the trigger's binding information
(trig_binding) can be changed.
sec_attr_schema_part_comment
If set, indicates whether or not comments associated with
the schema entry (comment) can be changed.
sec_attr_component_name_t
A pointer to a character string used to further specify the object
to which the attribute is attached. (Note that this data type is
analogous to the sec_acl_component_name_t data type in the ACL
interface.)
sec_attr_cursor_t
A structure that provides a pointer into a registry database and is
used for multiple database operations.
This cursor must minimally represent the object indicated by
xattrschema in the schema interfaces, or component_name in the
attribute interfaces. The cursor may additionally represent an
entry within that schema or an attribute instance on that component.
sec_attr_srch_cursor_t
A structure that provides a pointer into a registry database and is
used for multiple database operations. The cursor must minimally
represent the list of all objects managed by this server that
possess the search attributes specified in the
sec_attr_srch_cursor_init routine. It may additionally represent
a given object within this list as well as attribute instance(s)
possessed by that object.
sec_attr_trig_cursor_t
A structure that provides an attribute trigger cursor for inter-
active operations. The structure consists of the following
elements:
source A value of type uuid_t that provides a UUID to identify
the server that initialized the cursor.
object_handle
A signed 32 bit integer that identifies the object
(specified by xattrschema in the schema interface or
component_name in the attribute interface) upon which
the operation is being performed.
entry_handle
A signed 32 bit integer that identifies the current entry
(schema_entry in the schema interface or attribute
instance in the attribute interface) for the operation.
valid A boolean field with the following values:
+ true (1) - Indicates an initialized cursor.
+ false (0) - Indicates an uninitialized cursor.
sec_attr_trig_timeval_sec_t
A 32-bit integer containing the seconds portion of a UNIX timeval_t,
to be used when expressing absolute dates.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_ATTR_BASE.IDL
The idl file from which sec_attr_base.h was derived.
CONSTANTS
The following constants are used in sec_attr calls:
sec_attr_bind_auth_dce
The binding uses DCE shared-secret key authentication.
sec_attr_bind_auth_none
The binding is not authenticated.
sec_attr_bind_type_string
The attribute uses an rpc string binding.
sec_attr_bind_type_svrname
The attribute uses a name in rpc_c_ns_syntax format that identifies
a CDS entry containing the server's binding information. This
constant has the following structure:
name_syntax
Must be rpc_c_ns_syntax_dce to specify that DCE naming
rules are used to specify name.
name A pointer to a name of a CDS entry in rpc_c_ns_syntax_dce
syntax.
sec_attr_bind_type_twr
The attribute uses a DCE protocol tower binding representation.
sec_attr_trig_type_t Constants
The following 32-bit constants are used with the
sec_attr_trig_type_t data type:
sec_attr_trig_type_query The trigger server can perform only
query operations.
sec_attr_trig_type_update The trigger server can perform only
update operations.
sec_attr_intercell_action_t Constants
The following constants are used with the
sec_attr_intercell_action_t data type
sec_attr_intercell_act_accept
If the unique flag in the sec_attr_schema_entry_t data type is
not set on, retain attributes from a foreign cell. If the unique
flag is set on, retain the foreign attribute only if its value
is unique among all attribute instances of the same attribute
type within the cell.
sec_attr_intercell_act_reject
Discard attributes from a foreign cell.
sec_attr_intercell_act_evaluate
A trigger server determines whether to retain foreign
attributes, discard foreign attributes, or map foreign
attribute to another value(s).
sec_attr_schema_entry_parts_t Constants
The following constants are used with the
sec_attr_schema_entry_parts_t data type:
sec_attr_schema_part_name
Indicates that the attribute name can be changed in an schema
update operation.
sec_attr_schema_part_reserved
Indicates that the setting of the reserved flag can be changed
in a schema entry update.
sec_attr_schema_part_defaults
Indicates that the apply_default flag can be changed in a schema
entry update operation.
sec_attr_schema_part_trig_bind
Indicates that trigger binding information can be changed in a
schema entry update operation.
sec_attr_schema_part_comment
Indicates that comments associated with the schema entry can be
changed in a schema entry update.
3 – LOGIN_API_DATA_TYPES
SYNOPSIS
#include <dce/sec_login.h>
DATA TYPES
The following data types are used in sec_login_ calls:
sec_login_handle_t
This is an opaque pointer to a data structure representing a
complete login context. The context includes a principal's network
credentials, as well as other account information. The network
credentials are also referred to as the principal's "ticket-granting
ticket."
sec_login_flags_t
A 32-bit set of flags describing restrictions on the use of a
principal's validated network credentials. Currently, only one flag
is implemented, and the set can take on the following two values:
sec_login_no_flags
No special flags are set.
sec_login_credentials_private
Restricts the validated network credentials to the current
process. If this flag is not set, it is permissible to
share credentials with descendents of current process.
sec_login_auth_src_t
An enumerated set describing how the login context was authorized.
The possible values are:
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 login contexts authenticated locally
have no network credentials, they may not be used for
network operations.
sec_login_auth_src_overridden
Authentication accomplished via the override facility.
sec_login_passwd_t
The sec_login_get_pwent() call will return a pointer to a "password"
structure, which depends on the underlying registry structure. In
most cases, the structure will look like that supported by Berkeley
4.4BSD and OSF/1, which looks like this:
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; * Honeywell login info *
char *pw_dir; * home directory *
char *pw_shell; * default shell *
time_t pw_expire; * account expiration *
};
sec_passwd_rec_t
A structure containing either a plaintext password or a preencrypted
buffer of password data. The sec_passwd_rec_t structure consists of
three components:
version_number
The version number of the password.
pepper A character string combined with the password before an
encryption key is derived from the password.
key A structure consists of the following components:
key_type
The key type can be the following:
sec_passwd_plain
Indicates that a printable string of data is
stored in plain.
sec_passwd_des
Indicates that an array of data is stored in
des_key.
tagged_union
A structure specifying the password. The value of
the structure depends on key_type. If key_type is
sec_passwd_plain, structure contains plain, a
character string. If key_type is sec_passwd_des,
the structure contains des_key, a DES key of type
sec_passwd_des_key_t.
CONSTANTS
The following constants are used in sec_login_ calls:
sec_login_default_handle
The value of a login context handle before setup or validation.
sec_login_flags_t Constants
The following two constants are used with the sec_login_flags_t
type.
sec_login_no_flags
No special flags are set.
sec_login_credentials_private
Restricts the validated network credentials to the current
process. If this flag is not set, it is permissible to
share credentials with descendents of current process.
sec_login_remote_uid
Used in the sec_login_passwd_t structure for users from remote
cells.
sec_login_remote_gid
Used in the sec_login_passwd_t structure for users from remote
cells.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which sec_login.h was derived.
4 – EXTENDED_PRIVILEGE_ATTRIBUTE_API_DATA_TYPES
SYNOPSIS
#include <dce/id_epac.h>
#include <dce/nbase.h>
DATA TYPES
The following data types are used in Extended Privilege Attribute calls
and in the sec_login_cred calls that implement extended privilege
attributes.
sec_cred_cursor_t
A structure that provides an input/output cursor used to iterate
through a set of delegates in the sec_cred_get_delegate() or
sec_login_cred_get_delegate() calls. This cursor is initialized by
the sec_cred_initialize_cursor() or sec_login_cred_init_cursor()
call.
sec_cred_attr_cursor_t
A structure that provides an input/output cursor used to iterate
through a set of extended attributes in the
sec_cred_get_extended_attributes() call. This cursor is initialized
by the sec_cred_initialize_attr_cursor() call.
sec_id_opt_req_t
A structure that specifies application-defined optional
restrictions. The sec_id_opt_req_t data type is composed of the
following elements:
restriction_len
An unsigned 16-bit integer that defines the size of the
restriction data.
restrictions
A pointer to a byte_t that contains the restriction data.
sec_rstr_entry_type_t
An enumerator that specifies the entry types for delegate and target
restrictions. This data type is used in conjunction with the
sec_id_restriction_t data type where the specific UUID(s), if
appropriate, are supplied. It consists of the following components:
sec_rstr_e_type_user
The target is a local principal identified by UUID. This
type conforms with the POSIX 1003.6 standard.
sec_rstr_e_type_group
The target is a local group identified by UUID. This type
conforms with the POSIX 1003.6 standard.
sec_rstr_e_type_foreign_user
The target is a foreign principal identified by principal
and cell UUID.
sec_rstr_e_type_foreign_group
The target is a foreign group identified by group and cell
UUID.
sec_rstr_e_type_foreign_other
The target is any principal that can authenticate to the
foreign cell identified by UUID.
sec_rstr_e_type_any_other
The target is any principal that can authenticate to any
cell, but is not identified in any other type entry.
sec_rstr_e_type_no_other
No pincipal can act as a target or delegate.
sec_id_restriction_t
A discriminated union that defines delegate and target restrictions.
The union, which is used in conjunction with the
sec_restriction_set_t data type, consists of the following elements:
entry_type
A sec_rstr_entry_type_t that defines the ACL entry types
for delegate and target restrictions. The value of
tagged_union depends on the value of entry_type.
tagged_union
A tagged union whose contents depend on entry_type as fol-
lows:
If entry_type is... Then tagged_union is...
________________________________________________________________
sec_rstr_e_type_any_other NULL
________________________________________________________________
sec_rstr_e_type_foreign_other foreign_id that identifies
the foreign cell.
________________________________________________________________
sec_rstr_e_type_user id, a sec_id_t that
sec_rstr_e_type_group identifies the user or group.
________________________________________________________________
sec_rstr_e_type_foreign_user foreign_id, a sec_id_foreign_t
sec_rstr_e_type_foreign_group that identifies the foreign user
or group.
sec_id_restriction_set_t
A structure that that supplies delegate and target restrictions. The
structure consists of:
num_restrictions
A 16-bit unsigned integer that defines the number of
restrictions in restrictions.
restrictions
A pointer to a sec_id_restriction_t that contains the res-
trictions.
sec_id_compatibility_mode_t
A unsigned 16 bit integer that defines the compatibility between
current and pre-1.1 servers. The data type uses the following con-
stants:
sec_id_compat_mode_none
Compatibility mode is off.
sec_id_compat_mode_initiator
Compatibility mode is on. The 1.0 PAC data extracted from
the EPAC of the chain initiator.
sec_id_compat_mode_caller
Compatibility mode is on. The 1.0 PAC data extracted from
the last delegate in the delegation chain.
sec_id_delegation_type_t
An unsigned 16 bit integer that defines the delegation type. The
data type uses the following constants:
sec_id_deleg_type_none
Delegation is not allowed.
sec_id_deleg_type_traced
Traced delegation is allowed.
sec_id_deleg_type_impersonation
Simple (impersonation) delegation is allowed.
sec_id_pa_t
An structure that contains pre-1.1 PAC data extracted from an EPAC
of a current version server. This data type, which is used for
compatibility with pre-1.1 servers, consists of the following
elements:
realm A value of type sec_id_t that contains the UUID that
identifies the cell in which the principal associated
with the PAC exists.
principal A value of type sec_id_t that contains the UUID of the
principal.
group A value of type sec_id_t that contains the UUID of the
principal's primary group.
num_groups
An unsigned 16-bit integer that specifies the number of
groups in the principal's groupset.
groups An array of pointers to sec_id_ts that contain the UUIDs
of the each group in the principal's groupset.
num_foreign_groupsets
An unsigned 16-bit integer that specifies the number of
foreign groups for the principal's groupset.
foreign_groupsets
An array of pointers to sec_id_ts that contain the UUIDs
of the each group in the principal's groupset.
sec_id_pac_t
An structure that contains a pre-1.1 PAC. This data type, which is
used as output of the sec_cred_get_v1_pac call, consists of the
following elements:
pac_type A value of type sec_id_pac_format_t that can be used to
describe the PAC format.
authenticated
A boolean field that indicates whether or not the PAC is
authenticated (obtained from an authenticated source).
FALSE indicates that the PAC is not authenticated. No
authentication protocol was used in the rpc that trans-
mitted the identity of the caller. TRUE indicates that
the PAC is authenticated.
realm A value of type sec_id_t that contains the UUID that
identifies the cell in which the principal associated
with the PAC exists.
principal A value of type sec_id_t that contains the UUID of the
principal.
group For local principals, a value of type sec_id_t that
contains the UUID of the principal's primary group.
num_groups
An unsigned 16-bit integer that specifies the number of
groups in the principal's groupset.
groups An array of pointers to sec_id_ts that contain the UUIDs
of the each group in the principal's groupset.
num_foreign_groups
An unsigned 16-bit integer that specifies the number of
foreign groups in the principal's groupset.
foreign_groups
An array of pointers to sec_id_ts that contain the UUIDs
of the each foreign group in the principal's groupset.
sec_id_pac_format_t
An enumerator that can be used to describe the PAC format.
sec_id_t
A structure that contains UUIDs for principals, groups, or organiza-
tions and an optional printstring name. Since a UUID is an handle
for the object's identity, the sec_id_t data type is the basic unit
for identifying principals, groups, and organizations.
Because the printstring name is dynamically allocated, this datatype
requires a destructor function. Generally, however, the sec_id_t is
embedded in other data types (ACLs, for example), and these data-
types have a destructor function to release the printstring storage.
The sec_id_t data type is composed of the following elements:
uuid A value of type uuid_t, the UUID of the principal, group,
or organization.
name A pointer to a character string containing the name of the
principal, group, or organization.
sec_id_foreign_t
A structure that contains UUIDs for principals, groups, or organiza-
tions for objects in a foreign cell and the UUID that identifies the
foreign cell. The sec_id_foreign_t data type is composed of the
following elements:
id A value of type sec_id_t that contains the UUIDs of the
objects from the foreign cell.
realm A value of type sec_id_t that contains the UUID of the
foreign cell.
sec_id_foreign_groupset_t
A structure that contains UUIDs for set of groups in a foreign
cell and the UUID that identifies the foreign cell. The
sec_id_foreign_groupset_t data type is composed of the following
elements:
realm A value of type sec_id_t that contain the UUID of the
foreign cell.
num_groups
An unsigned 16-bit integer specifying the number of group
UUIDs in groups.
groups A printer to a sec_id_t that contains the UUIDs of the
groupset from the foreign cell.
CONSTANTS
The following constants are used in the Extended Privilege Attribute
calls and in the the sec_login calls that implement extended privilege
attributes:
sec_id_compat_mode_none
Compatibility mode is off.
sec_id_compat_mode_initiator
Compatibility mode is on. The 1.0 PAC data extracted from the EPAC
of the chain initiator.
sec_id_compat_mode_caller
Compatibility mode is on. The 1.0 PAC data extracted from the last
delegate in the delegation chain.
sec_id_deleg_type_none
Delegation is not allowed.
sec_id_deleg_type_traced
Traced delegation is allowed.
sec_id_deleg_type_impersonation
Simple (impersonation) delegation is allowed.
sec_rstr_e_type_user
The delegation target is a local principal identified by UUID. This
type conforms with the POSIX 1003.6 standard.
sec_rstr_e_type_group
The delegation target is a local group identified by UUID. This type
conforms with the POSIX 1003.6 standard.
sec_rstr_e_type_foreign_user
The delegation target is a foreign principal identified by principal
and cell UUID.
sec_rstr_e_type_foreign_group
The delegation target is a foreign group identified by group and
cell UUID.
sec_rstr_e_type_foreign_other
The delegation target is any principal that can authenticate to the
foreign cell identified by UUID.
sec_rstr_e_type_any_other
The delegation target is any principal that can authenticate to any
cell, but is not identified in any other type entry.
sec_rstr_e_type_no_other
No principal can act as a target or delegate.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_CRED.IDL
The idl file from which sec_cred.h was derived.
SYS$COMMON:[DCE$LIBRARY]ID_EPAC.IDL
The idl file from which id_epac.h was derived.
SYS$COMMON:[DCE$LIBRARY]NBASE.IDL
The idl file from which nbase.h was derived.
5 – ACL_API_DATA_TYPES
SYNOPSIS
#include <dce/aclbase.h>
Data Types
The following data types are used in sec_acl_ calls:
sec_acl_handle_t
A pointer to an opaque handle bound to an ACL that is the subject
of a test or examination. The handle is bound to the ACL with
sec_acl_bind(). An unbound handle has the value
sec_acl_default_handle.
sec_acl_posix_semantics_t
A flag that indicates which, if any, POSIX ACL semantics an ACL
manager supports. The following constants are defined for use
with the sec_acl_posix_semantics_t data type:
sec_acl_posix_no_semantics
The manager type does not support POSIX semantics.
sec_acl_posix_mask_obj
The manager type supports the mask_obj entry type and
POSIX 1003.6 Draft 12 ACL mask entry semantics.
sec_acl_t
This data type is the fundamental type for the ACL manager
interfaces. The sec_acl_t type contains a complete access control
list, made up of a list of entry fields (type sec_acl_entry_t).
The default cell identifies the authentication authority for
simple ACL entries (foreign entries identify their own foreign
cells). The sec_acl_manager_type identifies the manager to
interpret this ACL. The sec_acl_t type is a structure containing
the following fields:
default_realm
A structure of type sec_acl_id_t, this identifies the UUID
and (optionally) the name of the default cell.
sec_acl_manager_type
Contains the UUID of the ACL manager type.
num_entries
An unsigned 32-bit integer containing the number of ACL
entries in this ACL.
sec_acl_entries
An array containing num_entries pointers to different ACL
entries, each of type sec_acl_entry_t.
sec_acl_p_t
This data type, simply a pointer to a sec_acl_t, is for use with the
sec_acl_list_t data type.
sec_acl_list_t
This data type is a structure containing an unsigned 32-bit integer
num_acls that describes the number of ACLs indicated by its
companion array of pointers, sec_acls, of type sec_acl_p_t.
sec_acl_entry_t
The sec_acl_entry_t type is a structure made up of the following
components:
perms A set of flags of type sec_acl_permset_t that describe the
permissions granted for the principals identified by this
ACL entry. Note that if a principal matches more than one
ACL entry, the effective permissions will be the most
restrictive combination of all the entries.
entry_info
A structure containing two members:
entry_type
A flag of type sec_acl_entry_type_t, indicating
the type of ACL entry.
tagged_union
A tagged union whose contents depend on the type
of the entry.
The types of entries indicated by entry_type can be the following:
sec_acl_e_type_user_obj
The entry contains permissions for the implied user object. This
type is described in the POSIX 1003.6 standard.
sec_acl_e_type_group_obj
The entry contains permissions for the implied group object.
This type is described in the POSIX 1003.6 standard.
sec_acl_e_type_other_obj
The entry contains permissions for principals not otherwise
named through user or group entries. This type is described
in the POSIX 1003.6 standard.
sec_acl_e_type_user
The entry contains a key that identifies a user. This type is
described in the POSIX 1003.6 standard.
sec_acl_e_type_group
The entry contains a key that identifies a group. This type is
described in the POSIX 1003.6 standard.
sec_acl_e_type_mask_obj
The entry contains the maximum permissions for all entries other
than mask_obj, unauthenticated, user_obj, other_obj.
sec_acl_e_type_foreign_user
The entry contains a key that identifies a user and the foreign
realm.
sec_acl_e_type_foreign_group
The entry contains a key that identifies a group and the foreign
realm.
sec_acl_e_type_foreign_other
The entry contains a key that identifies a foreign realm. Any
user that can authenticate to the foreign realm will be allowed
access.
sec_acl_e_type_any_other
The entry contains permissions to be applied to any accessor who
can authenticate to any realm, but is not identified in any
other entry (except sec_acl_e_type_unauthenticated).
sec_acl_e_type_unauthenticated
The entry contains permissions to be applied when the accessor
does not pass authentication procedures. A privilege attribute
certificate will indicate that the caller's identity is not
authenticated. The identity is used to match against the
standard entries, but the access rights are masked by this mask.
If this mask does not exist in an ACL, the ACL is assumed to
grant no access and all unauthenticated access attempts will be
denied.
Great care should be exercised when allowing unauthenticated
access to an object. Almost by definition, unauthenticated
access is very easy to spoof. The presence of this mask on
an ACL essentially means that anyone can get at least as much
access as allowed by the mask.
sec_acl_e_type_extended
The entry contains additional "pickled" data. This kind of
entry cannot be interpreted, but can be used by an out-of-date
client when copying an ACL from one manager to another
(assuming that the two managers each understand the data).
The contents of the tagged union depend on the entry type.
For the following entry types, the union contains a UUID and an optional
print string (called entry_info.tagged_union.id with type sec_id_t) for
an identified local principal, or for an identified foreign realm.
+ sec_acl_e_type_user
+ sec_acl_e_type_group
+ sec_acl_type_foreign_other
For the following entry types, the union contains two UUIDs and optional
print strings (called entry_info.tagged_union.foreign_id with type
sec_id_foreign_t) for an identified foreign principal and its realm.
+ sec_acl_e_type_foreign_user
+ sec_acl_e_type_foreign_group
For an extended entry (sec_acl_e_type_extended), the union contains
entry_info.tagged_union.extended_info, a pointer to an information block
of type sec_acl_extend_info_t.
sec_acl_permset_t
A 32-bit set of permission flags. The flags currently represent the
conventional file system permissions (read, write, execute) and the
extended DFS permissions (owner, insert, delete). The "unused"
flags represent permissions that can only be interpreted by the
manager for the object. For example, sec_acl_perm_unused_00000080
may mean to one ACL manager that withdrawals are allowed, and to
another ACL manager that rebooting is allowed.
The following constants are defined for use with the
sec_acl_permset_t data type:
sec_acl_perm_read
The ACL allows read access to the protected object.
sec_acl_perm_write
The ACL allows write access to the protected object.
sec_acl_perm_execute
The ACL allows execute access to the protected object.
sec_acl_perm_control
The ACL allows the ACL itself to be modified.
sec_acl_perm_insert
The ACL allows insert access to the protected object.
sec_acl_perm_delete
The ACL allows delete access to the protected object.
sec_acl_perm_test
The ACL allows access to the protected object only to the
extent of being able to test for existence.
The bits from 0x00000080 to 0x80000000 are not used by the
conventional ACL permission set. Constants of the form
sec_acl_perm_unused_00000080 have been defined so application
programs can easily use these bits for extended ACLs.
sec_acl_extend_info_t
This is an extended information block, provided for future
extensibility. Primarily, this allows an out-of-date client to
read an ACL from a newer manager and apply it to another (up-to-
date) manager. The data cannot be interpreted by the out-of-date
client without access to the appropriate "pickling" routines
(that presumably are unavailable to such a client).
In general, ACL managers should not accept ACLs that contain entries
the manager does not understand. The manager clearly cannot perform
the security service requested by an uninterpretable entry, and it
is considered a security breach to lead a client to believe that the
manager is performing a particular class of service if the manager
cannot do so.
The data structure is made up of the following components:
extension_type
The UUID of the extension type.
format_label
The format of the label, in ndr_format_t form.
num_bytes An unsigned 32-bit integer indicating the number of bytes
containing the "pickled" data.
pickled_data
The byte array containing the "pickled" data.
sec_acl_type_t
The sec_acl_type_t type differentiates among the various types of
ACLs an object can possess. Most file system objects will only
have 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. For example, a directory can have
three different ACLs: the directory ACL, controlling access to the
directory; the initial object (or default object) ACL, which serves
as a mask when creating new objects in the directory; and the
initial directory (or default directory) ACL, which serves as a
mask when creating new directories (containers).
The sec_acl_type_t is an enumerated set containing one of the
following values:
sec_acl_type_object
The ACL refers to the specified object.
sec_acl_type_default_object
The ACL is to be used when creating objects in the
container.
sec_acl_type_default_container
The ACL is to be used when creating nested containers.
The following values are defined but not currently used. They are
available for application programs that may create an application-
specific ACL definition.
sec_acl_type_unspecified_3
sec_acl_type_unspecified_4
sec_acl_type_unspecified_5
sec_acl_type_unspecified_6
sec_acl_type_unspecified_7
sec_acl_printstring_t
A sec_acl_printstring_t structure contains a printable representa-
tion for a permission in a sec_acl_permset_t permission set. This
allows a generic ACL editing tool to be used for application-
specific ACLs. The tool need not know the printable representation
for each permission bit in a given permission set. The
sec_acl_get_printstring() function will query an ACL manager for
the print strings of the permissions it supports.
The structure consists of 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 may
be used to describe the specified permission.
permissions
A sec_acl_permset_t permission set describing the
permissions that will be represented with the specified
print string.
sec_acl_component_name_t
This type is a pointer to a character string, to be used to specify
the entity a given ACL is protecting.
CONSTANTS
The following constants are used in sec_acl_ calls:
sec_acl_default_handle
The value of an unbound ACL manager handle.
sec_rgy_acct_key_t Constants
The following 32-bit integer constants are used with the
sec_rgy_acct_key_t data type:
sec_rgy_acct_key_none
Invalid key.
sec_rgy_acct_key_person
The person name alone is enough.
sec_rgy_acct_key_group
The person and group names are both necessary for the
account abbreviation.
sec_rgy_acct_key_org
The person, group, and organization names are all
necessary.
sec_rgy_acct_key_last
Key values must be less than this constant.
sec_rgy_pname_t_size
The maximum number of characters in a sec_rgy_pname_t.
sec_acl_permset_t Constants
The following constants are defined for use with the
sec_acl_permset_t data type:
sec_acl_perm_read
The ACL allows read access to the protected object.
sec_acl_perm_write
The ACL allows write access to the protected object.
sec_acl_perm_execute
The ACL allows execute access to the protected object.
sec_acl_perm_owner
The ACL allows owner-level access to the protected object.
sec_acl_perm_insert
The ACL allows insert access to the protected object.
sec_acl_perm_delete
The ACL allows delete access to the protected object.
sec_acl_perm_test
The ACL allows access to the protected object only to the
extent of being able to test for existence.
sec_acl_perm_unused_00000080 - sec_acl_perm_unused_0x80000000
The bits from 0x00000080 to 0x80000000 are not used by
the conventional ACL permission set. Constants have
been defined so application programs can easily use
these bits for extended ACLs.
sec_acl_printstring_len
The maximum length of the printable representation of an ACL permis-
sion. (See sec_acl_printstring_t.)
sec_acl_printstring_help_len
The maximum length of a help message to be associated with a
supported ACL permission. (See sec_acl_printstring_t.)
FILES
SYS$COMMON:[DCE$LIBRARY]ACLBASE.IDL
The idl file from which aclbase.h was derived.
6 – KEY_MANAGEMENT_API_DATA_TYPES
NOTES
Key management operations that take a keydata argument expect a pointer
to a sec_passwd_rec_t structure, and those that take a keytype argument
(void *) expect a pointer to a sec_passwd_type_t. Key management
operations that yield a keydata argument as output set the pointer to
an array of sec_passwd_rec_t. (The array is terminated by an element
with a key type of sec_passwd_none.)
Operations that take a keydata argument expect a pointer to a
sec_passwd_rec_t structure. Operations that yield a keydata argument
as output set the pointer to an array of sec_passwd_rec_t. (The array
is terminated by an element with key type sec_passwd_none.) Operations
that take a keytype argument (void *) expect a pointer to a
sec_passwd_type_t.
SYNOPSIS
#include <dce/keymgmt.h>
DATA TYPES
An enumerated set describing the currently supported key types. The
possible values are:
Indicates no key types are supported.
Indicates that the key is a printable string of data.
Indicates that the key is DES encrypted data.
sec_passwd_rec_t
A structure containing either a plaintext password or a preencrypted
buffer of password data. The sec_passwd_rec_t structure consists of
three components:
version_number
The version number of the password.
pepper A character string combined with the password before an
encryption key is derived from the password.
key A structure consists of the following components:
key_type
The key type can be the following:
sec_passwd_plain
Indicates that a printable string of data is
stored in plain.
sec_passwd_des
Indicates that an array of data is stored in
des_key.
tagged_union
A structure specifying the password. The value of
the structure depends on key_type. If key_type is
sec_passwd_plain, structure contains plain, a
character string. If key_type is sec_passwd_des,
the structure contains des_key, a DES key of type
sec_passwd_des_key_t.
sec_passwd_version_t
An unsigned 32-bit integer that defines the password version number.
You can supply a version number or a 0 for no version number. If
you supply the constant sec_passwd_c_version_none, the Security
service supplies a system-generated version number.
A 32-bit unsigned integer whose purpose is to indicate the authenti-
cation service in use, since a server may have different keys for
different levels of security. The possible values of this data type
and their meanings are as follows:
rpc_c_authn_none
No authentication.
rpc_c_authn_dce_private
DCE private key authentication (an implementation of the
Kerberos system).
rpc_c_authn_dce_public
DCE public key authentication (reserved for future use).
Constants
There are no constants specially defined for use with the key management
API.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which keymgmt.h was derived.
7 – ID_MAPPING_API_DATA_TYPES
SYNOPSIS
#include <dce/secidmap.h>
DATA TYPES
No special data types are defined for the ID Mapping API.
CONSTANTS
No special constants are defined for the ID Mapping API.
FILES
SYS$COMMON:[DCE$LIBRARY]SECIDMAP.IDL
The idl file from which secidmap.h was derived.
8 – PASSWORD_MANAGEMENT_API_DATA_TYPES
SYNOPSIS
#include <dce/sec_pwd_mgmt.h>
DATA TYPES
The following data types are used in sec_pwd_mgmt_ calls:
A pointer to an opaque handle consisting of password management
information about a principal. It is returned by
sec_pwd_mgmt_setup().
CONSTANTS
There are no constants specially defined for use with the Password
Management API.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_PWD_MGMT.IDL
The idl file from which sec_pwd_mgmt.h was derived.