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 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 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:
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:
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. |
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:
| 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. |
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. |
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. |
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. |
The structure identifying a registry item. It contains five components:
| 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. |
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_user_to_user | Forces the use of user-to-user 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. |
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. |
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.
| 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. |
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. |
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. |
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 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. |
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. |
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, path names 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.