NAME

sec_intro — Application program interface to the DCE Security Service

Description

The 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:

rgyMaintains the network registry of principal identities. 

eraMaintains extended registry attributes. 

loginValidates a principal’s network identity and establish delegated identities. 

epaExtracts privilege attributes from an opaque binding handle. 

aclImplements an access control list (ACL) protocol for the authorization of a principal to network access and services. 

keyProvides facilities for the maintenance of account keys for daemon principals. 

idMaps file system names to universal unique IDs (UUIDs). 

pwd_mgmt
Provides facilities for password management.

pkProvides facilities for public key authentication. 

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(1) tool is written with sec_rgy calls, acl_edit(1) is written with sec_acl calls, and the login(1) 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

   •Public Key APIs

The section for each API is organized as follows:

   •Synopsis

   •Data Types

   •Constants

   •Files

Registry API Data Types

Synopsis

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_infoA 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:

Protection Level	Description
_	_
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.
_	_

Protection Level	Description
_	_
rpc_c_protect_level_pkt_integ	Ensures and verifies that none of the data transferred 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:

Authentication Service	Description
_	_
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 authentication service.  The current default authentication 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:

Authentication Service	Description
_	_
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).
_	_

identityA 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:

pnameThe person name for the account. 

gnameThe group name for the account. 

onameThe organization name for the account. 

sec_rgy_member_t
A character string of length sec_rgy_name_t_size. 

sec_rgy_foreign_id_t
The representation of a foreign ID.  This structure contains two components:

cellA string of type uuid_t representing the UUID of the foreign cell. 

principalA string of type uuid_t representing the UUID of the principal. 

sec_rgy_sid_t
A structure identifying an account.  It contains three fields:

personThe UUID of the person part of the account. 

groupThe UUID of the group part of the account. 

orgThe 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:

personThe UNIX ID of the person part of the account. 

groupThe UNIX ID of the group part of the account. 

orgThe 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 components:

idThe UUID of the registry item, in uuid_t form. 

unix_num
A 32-bit integer containing the UNIX ID number of the registry item.

quotaA 32-bit integer representing the maximum number of user-defined groups the account owner can create. 

flagsA sec_rgy_pgo_flags_t bitset containing information about the entry. 

fullnameA 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 the following flags:

sec_rgy_acct_auth_user_to_user
Forces the use of user-to-user server authentication on a server principal.

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. 

creatorThis 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. 

flagsAdministrative 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 password 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 user; the remaining fields are set by the security server. 

gecosThis 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. 

homedirThe login directory for the account user, in sec_rgy_pname_t format. 

shellThe 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.

passwdThe 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. 

flagsAccount 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 be the more restrictive of the site and principal authentication 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 software 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.

flagsProperty flags, in sec_rgy_properties_flags_t format. 

realmThe 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. 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:

   0.The registry permits the requested overrides to be set for this machine. 

   1.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.  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
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
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

/usr/include/dce/rgybase.idl
The idl file from which rgybase.h was derived. 

Extended Registry Attribute Data Types

Synopsis

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:

countAn 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. 

nameA 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 (see table) 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 a 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 authenticated.  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:

Protection Level	Description
_	_
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.
_	_

Protection Level	Description
_	_
rpc_c_protect_level_pkt_integ	Ensures and verifies that none of the data transferred 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:

Authentication Service	Description
_	_
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 authentication service.  The current default authentication 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:

Authentication Service	Description
_	_
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 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. 

bindingsAn 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 information 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

lengthAn 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

codesetAn unsigned 32-bit identifier of a codeset registered with the Open Software Foundation. 

lengthAn 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 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_idA 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 Type	ACL Manager Type	Valid 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 elements:

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:

sec_attr_trig_type_query
The attribute trigger server is invoked for query operations.

sec_attr_trig_type_query
The attribute trigger server is invoked for update operations.

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 elements:

attr_name
A pointer to the attribute name.

attr_idA 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:

uniqueWhen 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 multivalued; 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.

reservedWhen 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. 

scopeA pointer to a string that defines the objects to which the attribute can be attached. 

commentA 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 determines 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 nonexistent 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 interactive operations. The structure consists of the following elements:

sourceA 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. 

validA 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

/usr/include/dce/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. 

nameA 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
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
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
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.

Login API Data Types

Synopsis

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. Possible values are:

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_tpw_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.

pepperA character string combined with the password before an encryption key is derived from the password. 

keyA structure consists of the following components:

key_typeThe 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
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

/usr/include/dce/sec_login.idl
The idl file from which sec_login.h was derived. 

Extended Privilege Attribute API Data Types

Synopsis

#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 follows:

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 Sec_rstr_e_type_group	id, a sec_id_t that identifies the user or group.
_	_
sec_rstr_e_type_foreign_user sec_rstr_e_type_foreign_group	foreign_id, a sec_id_foreign_t 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 restrictions. 

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 constants:

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:

realmA value of type sec_id_t that contains the UUID that identifies the cell in which the principal associated with the PAC exists. 

principalA value of type sec_id_t that contains the UUID of the principal. 

groupA 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.

groupsAn 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_typeA 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 transmitted the identity of the caller. TRUE indicates that the PAC is authenticated.

realmA value of type sec_id_t that contains the UUID that identifies the cell in which the principal associated with the PAC exists. 

principalA value of type sec_id_t that contains the UUID of the principal. 

groupFor 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.

groupsAn 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_tA structure that contains UUIDs for principals, groups, or organizations 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 datatypes have a destructor function to release the printstring storage. 

The sec_id_t data type is composed of the following elements:

uuidA value of type uuid_t, the UUID of the principal, group, or organization. 

nameA 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 organizations 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:

idA value of type sec_id_t that contains the UUIDs of the objects from the foreign cell. 

realmA 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:

realmA 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. 

groupsA 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 pincipal can act as a target or delegate.

Files

/usr/include/dce/sec_cred.idl
The idl file from which sec_cred.h was derived. 

/usr/include/dce/sec_epac.idl
The idl file from which sec_epac.h was derived. 

/usr/include/dce/sec_nbase.idl
The idl file from which sec_nbase.h was derived. 

ACL API Data Types

Synopsis

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:

permsA 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 representation 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
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
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 permission. (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

/usr/include/dce/aclbase.idl
The idl file from which aclbase.h was derived. 

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

Data Types

sec_passwd_type_t
An enumerated set describing the currently supported key types.  The possible values are as follows:

sec_passwd_none
Indicates no key types are supported.

sec_passwd_plain
Indicates that the key is a printable string of data.

sec_passwd_des
Indicates that the key is DES encrypted data.

sec_passwd_privkey
Indicates that the key is a private or public key of a public key pair used in public key authentication.

sec_passwd_genprivkey
Indicates the modulus bit size of the private key to be generated for a public key pair used in public key authentication.

sec_passwd_rec_t
A structure containing any of the following: a plaintext password, a preencrypted buffer of password data, a public-key-pair generation request, or a public or private key. The sec_passwd_rec_t structure consists of three components:

version_number
The version number of the password.

pepperA character string combined with the password before an encryption key is derived from the password. 

keyA structure consists of the following components:

key_typeThe 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.

sec_passwd_privkey
Indicates that X.509 ASN.1 DER-encoded data is stored in priv_key. 

sec_passwd_genprivkey
Indicates that unsigned 32-bit data is stored in modulus_size. 

tagged_union
A structure specifying the password.  The value of the structure depends on key_type. 

If key_type is sec_passwd_plain, the 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. 

If key_type is sec_passwd_privkey, the structure contains priv_key, a public or private key of type sec_pk_data_t. 

If key_type is sec_passwd_genprivkey, the structure contains modulus_size, unsigned 32-bit data. 

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. 

sec_key_mgmt_authn_service
A 32-bit unsigned integer whose purpose is to indicate the authentication 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

/usr/include/dce/keymgmt.idl
The idl file from which keymgmt.h was derived. 

ID Mapping API Data Types

Synopsis

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

/usr/include/dce/secidmap.idl
The idl file from which secidmap.h was derived. 

Password Management API Data Types

Synopsis

Data Types

The following data types are used in sec_pwd_mgmt_ calls:

sec_passwd_mgmt_handle_t
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

/usr/include/dce/sec_pwd_mgmt.idl
The idl file from which sec_pwd_mgmt.h was derived. 

Public Key API Data Types

Synopsis

Data Types

The following data types are used in sec_pk calls:

sec_pk_domain_t
A UUID of type uuid_t associated with the application domain in which a public or private key is used. 

sec_pk_usage_flags_t
A 32k-bit set of key-usage flags that describe the use of a key or key pair.  The flags are:

sec_pk_usage_digitalSignature
 

sec_pk_usage_nonRepudiation
 

sec_pk_usage_keyEncipherment
 

sec_pk_usage_keyAgreement
 

sec_pk_usage_keyCertSign
 

sec_pk_usage_offLineCRLSign
 

These flags are described in the X.509 (1993E) AM 1 standard. 

sec_pk_data_t
A structure that points to an X.509 or X.511 ASN.1 DER-encoded value. The sec_pk_data_t data type acts as a base for the following data types, which are aliases for sec_pk_data_t:

sec_pk_gen_data_t

sec_pk_pubkey_t

sec_pk_pvtkey_t

sec_pk_signed_t

sec_pk_encrypted_t

sec_pk_algorithm_id_t

The alias data types indicate the specific information pointed to by sec_pk_data_t.  Instead of using sec_pk_data_t directly, use the alias data types. 

The sec_pk_data_t data type consists of the following elements:

lenThe size of data. 

dataA pointer to a character string. 

sec_pk_gen_data_t
A structure that acts as an alias to a sec_pk_data_t that contains plain ASCII data. 

sec_pk_pubkey_t
A structure that acts as an alias to a sec_pk_data_t that contains an X.509 ASN.1 DER-encoded value of type SubjectPublicKeyInfo.  This data type assumes that the public key infrastructure provides functions for generating a public key in this format. 

sec_pk_pvtkey_t
A structure that contains an X.509 ASN.1 DER-encoded private key value. The key format depends on the public key infrastructure.

This data type assumes that the public key infrastructure provides functions for generating a private key in this format. 

sec_pk_signed_t
A structure that contains an X.509 ASN.1 DER-encoded value of type SIGNED.  This data type assumes that the public key infrastructure provides functions for generating a public key in this format. 

sec_pk_encrypted_t
A structure that contains an X.509 ASN.1 DER-encoded value of type ENCRYPTED.  This data type assumes that the public key infrastructure provides functions for generating a public key in this format. 

sec_pk_algorithm_id_t
A structure that contains an X.509 ASN.1 DER-encoded value of type AlgorithmIdentifier.  This data type assumes that the public key infrastructure provides functions for generating a public key in this format. 

Constants

The following constants are used in sec_pk calls:

The following unsigned 32-bit constants, which are used with the sec_pk_usage_flags_t data type, correspond to KeyUsage types defined in DAM 1 (Dec 1995) to X.509 (1993):

sec_pk_usage_digitalSignature

sec_pk_usage_nonRepudiation

sec_pk_usage_keyEncipherment

sec_pk_usage_dataEncipherment

sec_pk_usage_keyAgreement

sec_pk_usage_keyCertSign

sec_pk_usage_offLineCRLSign

Files

/usr/include/dce/sec_pk_base.idl
The idl file from which sec_pk.h was derived.