DCE Security Services provide authentication and authorization within a cell and is based upon MIT's Kerberos private key encryption system.
1 – Admin Intro
NAME
sec_intro - Introduction to the DCE Security administrative commands
DESCRIPTION
This section describes DCE Security commands for system administration.
These commands are:
acl_edit Manages Access Control Lists (ACLs) for DCE objects
auditd Starts the DCE Audit Daemon
chpass Changes user information, such as login name, password, home
directory, password and account expiration dates,and login
shell. The implementation of this utility is platform-
specific. Use the chpass utility supplied your platform vendor
for changing user information.
dce_login Validates a principal's identity and obtains a principal's
network credentials. This command is used primarily during
DCE configuration. Use the login utility supplied by your
platform vendor for user login.
kdestroy Destroys your login context and credentials
kinit Obtains and caches a ticket granting ticket
klist Lists cached tickets
passwd_export
Updates local password and group files from DCE registry data
passwd_import
Creates DCE registry entries based on password and group file
entries
passwd_override
Establishes DCE registry overrides for a principal on a local
node
pwd_strengthd
Sample password management server
rgy_edit Edits the registry database
sec_admin Administers the Security Server
sec_create_db
Creates registry databases
secd The Security Server daemon
sec_salvage_db
Reconstructs or recovers a registry database
See the command's reference page for further information on each command.
1.1 – acl_edit
NAME
acl_edit - Edits or lists an object's ACLs
SYNOPSIS
acl_edit {[-e] pathname | -addr string_binding component_name}
[-ic | -io] [-n | -c] [command_line_subcommands] [-ngui]
[-v]
OPTIONS
-e pathname Specifies that the ACL on the Directory Service
entry is to be edited. You must specify the
pathname argument if you use the -e option. The
-e option is especially useful in case of an
ambiguous pathname. The pathname argument can be
interpreted in two ways if it is the name of a
leaf object in the Directory Service (that is, if
it is not the name of a directory). It can be
interpreted as the Directory Service entry itself,
or as the object (whatever it is) referenced by
that Directory Service entry. When such a path-
name is specified, the -e option directs acl_edit
to the ACL on the Directory Service entry.
-addr string_binding component_name
The -addr option lets you identify the object
whose ACLs you want to edit by supplying the RPC
binding handle of the ACL Manager that controls
access to the object (with the string_binding
argument) and the relative pathname of the object
(with the component_name argument). Because you
have identified the RPC binding handle, you can
specify only the object's relative pathname for
component_name. The most common way to identify
the object whose ACLs you want to manipulate
is through the pathname argument,described below.
The -addr option is used primarily by applications
that do not use the Directory Service, but do use
the generic ACL Manager. It can also be used if
the Directory Service is unavailable.
-ic For container objects only, specifies that the
object's Initial Container Creation ACL is to be
edited. The Initial Container Creation ACL is
applied by default to any containers created
within the ACL'd container. If this option is
specified and the object named in pathname is not
a container, an error is returned.
-io For container objects only, specifies that the
object's Initial Object Creation ACL is to be
edited. The Initial Object Creation ACL is applied
by default to any simple objects (that is, objects
that are not containers) created within the ACL'd
container. If this option is specified and the
object is not a container, an error is returned.
-n Specifies that a new mask should not be calculated.
This option is useful only for objects that
support the mask_obj entry type and that are
required to recalculate a new mask after they are
modified. If a modify operation creates a mask
that unintentionally adds permissions to an
existing acl entry, the modify causing the mask
recalculation will abort with an error unless you
specify either the -c or -n option.
-c Creates or modifies the object's mask_obj type
entry with permissions equal to the union of all
entries other than type user_obj, other_obj, and
unauthenticated. This creation or modification is
done after all other modifications to the ACL are
performed. The new mask is set even if it grants
permissions previously masked out. It is
recommended that you use this option only if not
specifying it results in an error. This option is
useful only for objects that support the mask_obj
entry type and are required to recalculate a new
mask after they are modified. If a modify
operation creates a mask that unintentionally adds
permissions to an existing acl entry, the modify
causing the mask recalculation will abort with an
error unless you specify either the -c or -n option.
If you specify the -c option for an ACL that does
not support mask_obj entry type, acl_edit returns
an error when it attempts to save the ACL, aborting
all subcommands supplied on the command line.
-ngui Specifies that a Graphical User Interface (GUI)
should not be used even if a GUI is available.
If your version of acl_edit supports a GUI and
your terminal is capable of using it, invoking
acl_edit without this option will bring up the GUI
mode. Use the -ngui option to bring up command-
line mode. However, if a GUI is not available, or
the terminal is not capable of using the GUI,
acl_edit comes up in command-line mode regardles
of wheter you supply this option or not.
-v Run in verbose mode.
ARGUMENTS
pathname The full pathname of the object whose ACL is to be
viewed or edited. If the object is in another
cell, pathname must be fully qualified to include
the cell identifier.
command_line_subcommands
The command-line subcommands, which act on the
object specified by pathname, are entered as part
of the command string that invokes acl_edit. Only
one command-line subcommand can be specified per
invocation. The commands follow. See the
description of the equivalent interactive
subcommand for a more detailed description of the
command functions.
-m [acl_entry] acl_entry...
Adds a new ACL entry or changes the
permissions of an existing entry. You
can enter multiple entries, each
separated by a space.
-p Purges all masked permissions (before
any other modifications are made). This
option is useful only for ACLs that
contain an entry of type mask_obj. Use it
to prevent unintentionally granting
permissions to an existing entry when a
new mask is calculated as a result of
adding or modifying an ACL entry.
-d [acl_entry] acl_entry...
Deletes an existing entry from the ACL
associated with the specified object.
You can enter multiple entries, each
separated by a space.
-s [acl_entry] acl_entry...
Replaces (substitutes) the ACL information
associated with this object with
acl_entry. All existing entries are
removed and replaced by the newly
specified entries. If you specify the -s
subcommand, you cannot specify the -f or
-k subcommand. You can enter multiple
entries, each separated by a space.
-f file Assigns the ACL information contained
in file to the object. All existing entries
are removed and replaced by the entries
in the file. If you specify the -f sub-
command, you cannot specify the -s or -k
subcommand.
-k Removes all entries, except entries of
type user_obj (if they are present).
If you specify the -k subcommand, you
cannot specify the -f or -s subcommand.
-l Lists the entries in the object's ACL.
The command-line subcommands are evaluated in the following order:
1.
-p
2.
-s or -f or -k
3.
-d
4.
-m
5.
-l
NOTES
With the exception of the following subcommands, this command is
replaced at Revision 1.1 by the dcecp command. This command may be
fully replaced by the dcecp command in a future release of DCE, and may
no longer be supported at that time.
+ abort
+ commit
+ exit
+ help
+ test access
DESCRIPTION
The acl_edit command is a client program that, when invoked, binds to
the specified object's ACL Manager (which is implemented in the object's
server), and allows the user to manipulate the object's ACL through the
standard DCE ACL interface. This interface is the sec_acl_...()
interface documented in the OSF DCE Application Development Reference.
The acl_edit command automatically binds to the server of the object
specified, and then communicates (through the standard DCE ACL
interface) with that server's ACL manager in response to user input.
Exactly what the object "specified" is depends partly on whether or not
the -e option is specified. Specifying -e means that you want to operate
on the Directory Service ACL - in other words, you want acl_edit to bind
to the CDS server and allow you to operate on the ACL maintained by that
server on the object's directory entry. If, on the the ACL on the object
to which the directory entry refers - then you simply omit the -e
option. The result will be that acl_edit will bind to that object's
server (the server must, of course, implement an ACL manager), giving
you access to the object's ACL.
All acl_edit subcommands act on the object specified by pathname when
you invoked acl_edit. You can invoke acl_edit in either command-line or
interactive mode:
+ To invoke acl_edit in command-line mode, enter the command, the
object's pathname, options, and the command-line subcommand on th
line that invokes acl_edit. Only one command-line subcommand can be
entered per acl_edit invocation.
+ To invoke acl_edit in interactive mode, enter only acl_edit, the
object's pathname, and options. The acl_edit prompt is then
displayed. In this mode, you enter interactive subcommands that
let you edit and view entries in the object's ACL and view help
information about the acl_edit command itself.
Changes you make in command-line mode are saved when you enter the
command.
In interactive mode, you must explicitly save your changes. To do so,
use the commit subcommand to save the changes without exiting acl_edit
or the exit subcommand to save the changes and exit acl_edit. Use the
abort subcommand to exit acl_edit and save none of the changes you have
made. When you invoke acl_edit for a specific object's ACL, that ACL is
not locked. This means that it is possible for multiple users to edit
the ACL simultaneously, with each change overwriting the previous
changes. For this reason, the number of users assigned rights to change
a particular ACL should be tightly controlled and limited to one user
if possible.
INTERACTIVE SUBCOMMANDS
The following subcommands are available when acl_edit is invoked in
interactive mode. All of the commands act on the ACL associated with the
object specified by pathname when acl_edit was invoked.
? Displays the available acl_edit subcommands.
ab[ort] Exits acl_edit without saving the changes to the object's ACL.
as[sign] filename
Applies the ACL entries in filename to the specified object.
This subcommand removes existing entries and replaces them
with the entries in the file.
c[ell] name
Sets the cell name to be associated with the ACL. This sub-
command is used primarily to facilitate copying ACLs to
different cells. The default cell name stays in place until
you run the subcommand again to change it.
co[mmit] Saves all changes to the ACL without exiting.
d[elete] acl_entry
Deletes the specified ACL entry.
e[xit] Exits from acl_edit, saving any changes to the object's ACL.
g[et_access]
Displays the permissions granted in the specified object's ACL
to the principal that invoked acl_edit.
h[elp] [command ...]
Initiates the help facility. If you enter only the command
help, acl_edit displays a list of all commands and their
functions. If you enter help and a command (or commands
separated by a space), acl_edit displays help information on
the specified commands. Entering help sec_acl_entry displays
information about ACL entries.
k[ill_entries]
Removes all ACL entries except the user_obj entry if it
exists.
l[ist] Lists the entries in the object's ACL.
m[odify] acl_entry [-n | -c]
Adds a new ACL entry or replaces an existing ACL entry. This
command affects a single ACL entry. To add or replace all of
an object's ACL entries, see the su[bstitute] subcommand. For
objects that support the mask_obj entry type and are required
to calculate a new mask when their ACLs are modified, the -n
option specifies that a new mask should not be calculated; the
-c option specifies that the object's mask_obj entry should
have permissions equal to the union of all entries other than
user_obj, other_obj, and unauthenticated. The mask is
calculated after the ACL is modified.
If you use the -c option, the new mask is set even if it
grants permissions previously masked out. It is recommended
that you use the -c option only if not specifying it results
in an error. If the new mask unintentionally grants
permissions to an existing entry, the modify operation
causing the mask recalculation will abort with an error
unless you specify either the -c or -n option.
p[ermissions]
Lists the available permission tokens and explanations.
pu[rge] Purges all masked permissions. This option is useful only
for ACLs that contain an entry of type mask_obj. Use it to
prevent unintentionally granting permissions to an existing
entry when a new mask is calculated as a result of adding or
modifying an ACL entry.
su[bstitute] acl_entry [acl_entry ...]
Replaces all ACL entries with the one or ones specified. This
subcommand removes all existing entries and adds the ones
specified by acl_entry. To replace only a single ACL entry,
see the m[odify] subcommand.
t[est_access] [permissions ...]
Tests whether or not the permissions specified in the command
are granted to the principal under whose DCE identity the
acl_edit command was invoked. The option returns Granted if
the permissions are granted or Denied if they are not.
ACL ENTRIES
An ACL entry has the following syntax:
type[:key]:permissions
where:
type Identifies the role of the ACL entry.
key Identifies the specific principal or group to whom
the entry applies. For an entry type of extended,
key contains the ACL data.
permissions The ACL permissions.
A thorough description of each syntax component follows.
Type The type tag identifies the role of the ACL entry.
Valid types are the following:
+ user_obj - Permissions for the object's real or
effective user.
+ group_obj - Permissions for the object's real or
effective group.
+ other_obj - Permissions for others in the local cell
who are not otherwise named by a more
specific entry type.
+ user - Permissions for a specific principal
user in the ACL's cell. This type of
ACL entry must include a key that
identifies the specific principal.
+ group - Permissions for a specific group in the
ACL's cell. This type of ACL entry must
include a key that identifies the
specific group.
+ foreign_user
Permissions for a specific, authenticated
user in a foreign cell. This type of ACL
entry must include a key that identifies
the specific principal and the principal's
cell.
+ foreign_group
Permissions for a specific, authenticated
group in a foreign cell. This type of ACL
entry must include a key that identifies
the specific group and the group's cell.
+ foreign_other
Permissions for all authenticated
principals in a specific foreign cell,
unless those principals are specifically
named in an ACL entry of type foreign_user
or members in a group named in an entry of
type foreign_group. This type of ACL
entry must include a key that identifies
the specific foreign cell.
+ any_other - Permissions for all authenticated
principals unless those principals match
a more specific entry in the ACL.
+ mask_obj - Permissions for the object mask that is
applied to all entry types except
user_obj, other_obj, and unauthenticated.
+ unauthenticated
Maximum permissions applied when the
accessor does not pass authentication
procedures. This entry is used for
principals that have failed authentica-
tion due to bad keys, principals who
are entirely outside of any authentication
cell, and principals who choose not to use
authenticated access. Permissions granted
to an unauthenticated principal are masked
with this entry, if it exists. If this
entry does not exist, access to
unauthenticated principals is always
denied.
+ extended - A special entry that allows client
applications running at earlier DCE
versions to copy ACLs to and from ACL
Managers running at the current DCE
version without losing any data. The
extended entry allows the application
running at the lower version to obtain a
printable form of the ACL. The extended
ACL entry has the following form:
extended:uuid.ndr.ndr.ndr.ndr.number_of_byte.data
where:
uuid Identifies the type extended ACL
entry. (This UUID can identify
one of the ACL entry types
described here or an as-yet-
undefined ACL entry type.)
ndr.ndr.ndr.ndr
Up to three Network Data
Representation (NDR) format labels
(in hexadecimal format and
separated by periods) that
identify the encoding of data.
number_of_bytes
A decimal number that specifies
the total number of bytes in data.
data The ACL data in hexadecimal form.
(Each byte of ACL data is two
hexadecimal digits.) The ACL data
includes all of the ACL entry
specifications except the
permissions (described later) that
are entered separately. The data
is not interpreted; it is assumed
that the ACL Manager to which the
data is being passed can understand
that data.
Key
The key identifier (principal or group name) specifies the principal or
group to which the ACL entry applies. For entries of entry type
extended, key is the data passed from one ACL Manager to another. A key
is required for the following types of ACL entries:
+ user - Requires a principal name only.
+ group - Requires a group name only.
+ foreign_user - Requires a fully qualified cell name in addition
to the principal name.
+ foreign_group - Requires a fully qualified cell name in addition
to the group name.
+ foreign_other - Requires a fully qualified cell name.
Permissions
The permissions argument specifies the set of permissions that defines
the access rights conferred by the entry. Since each ACL Manager defines
the permission tokens and meanings appropriate for the objects it
controls, the actual tokens and their meanings vary. For example, the
Distributed File Service, the Directory Service, and the Security
Registry Service each implemhent a separate ACL Manager, and each can
use a different set of tokens and permissions. This means that file
system objects, objects in the namespace, and registry objects could
each use different permissions. Use the p[ermissions] subcommand to
display the currently available tokens and their meanings. See the
documentation for the DCE component you are using to obtain a more
detailed description of its specific permissions.
EXAMPLES
1. The following example uses the interactive interface to set permis-
sions for the unauthenticated and mask_obj entry type:
sec_acl_edit> m mask_obj:rwx
sec_acl_edit> m unauthenticated:r
2. The following example uses the interactive interface to set permis-
sions for the effective user, group, and others in the ACL's cell:
sec_acl_edit> m user_obj:crwx
sec_acl_edit> m group_obj:rwx
sec_acl_edit> m other_obj:rwx
3. The following example uses the command-line interface to invoke
acl_edit and assign permissions for the file progress_chart to the
authenticated user mike in the local cell:
% acl_edit /.../dresden.com/fs/walden/progress_chart -m user:mike:cx
Note that because this entry will be filtered through the object
mask (mask_obj), which specifies only rwx permissions, the actual
permissions will be rwx, not crwx. The l(ist) subcommand will show
those permissions as follows:
user:mike:crwx #effective -rwx---
4. The following example uses the interactive interface to set permis-
sions for the authenticated foreign user named burati in the cell
named /.../usc-cs.uscal.edu:
sec_acl_edit> m foreign_user:/.../usc-cs.uscal.edu/sailing/staff/bux
5. The following example uses the non-interactive command-line inter-
face to invoke and set the Initial Container Creation
permissions for the directory that is named walden:
% acl_edit /.../dresden.com/fs/walden -ic -m /user:walden:crwxid
1.2 – chpass
NAME
chpass - Changes user database information
SYNOPSIS
chpass [user]
OPTIONS
None
ARGUMENTS
user The user argument indicates the user whose database informa-
tion you want to change. If omitted, you are prompted for
the user.
DESCRIPTION
The chpass command changes user database information associated with
user.
Note that the functionality of the chpass command as described in this
reference page can change depending on the platform on which you are
running the command. Each platform vendor integrates this command
(based on 4.4BSD source) with the vendor's own login facility.
You can edit information associated with user only if you are user or
have the appropriate rights.
chpass prompts for the information it needs. The information will
include all or a subset of the following list:
o Login - The login name used to access the account. Because the
login name controls file access, they must be unique within the
cell. In multicell environments, this uniqueness is ensured by
automatically appending the cell designator to the user's name.
While it is possible to have multiple entries with identical login
names, it is usually a mistake to do so. Routines that manipulate
these files will often return only one of the multiple entries,
and that one by random selection.
o Password - The encrypted account password.
Once the information has been verified, the network registry is
updated.
RELATED INFORMATION
COMMANDS: login
dce_login
1.3 – dce_login
NAME
dce_login - Validates a principal's identity and obtains the
principal's network credentials
SYNOPSIS
dce_login [principal_name] [password] [-c] [-e[xec] cmd_string]
OPTIONS
-c Causes the principal's identity to be certified. If you
do not specify -c, the principal's identity is validated
only.
[-e[xec] cmd_string] Executes the command supplied as cmd_string.
ARGUMENTS
principal_name The name of the principal to log in as.
password The password for principal_name.
DESCRIPTION
The dce_login command is supplied for use in DCE configuration. It vali-
dates a principal's identity and obtains the principal's network creden-
tials.
If the -c option is supplied, the command also certifies the principal's
identity, and, if the principal is able to be certified, creates an
entry for the principal in the machine's local registry. If the
principal is not able to be certified, the command attempts to log the
principal in via the local registry.
The -exec option executes the command specified by cmd_string after
login. If cmd_string is specified without a full pathname, the path
prefix is obtained by searching the directories according to the PATH
variable.
The principal_name argument specifies the name of the principal who is
logging in. The password argument specifies the principal's password.
If you do not supply a principal name or a principal password, dce_login
prompts for them. If you enter them both on the command line, you must
specify the principal name first, followed by the password.
The dce_login command executes the shell specified in the SHELL environ-
ment variable.
Note that if the clocks on the Security server and client machines are
not synchronized to within 2 or 3 minutes of each other, you may receive
a password validation error and be unable to be validated.
1.4 – kdestroy
NAME
kdestroy - Destroys a principal's login context and associated
credentials
SYNOPSIS
kdestroy [-c cache_name]
OPTIONS
-c cache_name Specifies that the login context and associated
credentials for cache_name should be destroyed
instead of the default cache.
DESCRIPTION
The kdestroy command destroys a principal's login context and the
principal's credentials. Until the credentials are reestablished by
either executing the dce_login command or the kinit command, the
principal and any processes created by the principal will be limited to
unauthenticated access.
FILES
dce$local:[var.security.creds]DCECRED*
If the KRB5CCNAME logical name is set, the
default credentials cache.
RELATED INFORMATION
COMMANDS: klist
kinit
1.5 – kinit
NAME
kinit - Obtains and caches ticket-granting ticket
SYNOPSIS
kinit [-c cachename] [-f] [-l lifetime] [-p] [-r lifetime] [-v]
[principal]
OPTIONS
-c cachename
Specifies an alternative credentials cache, cachename, to be
used in place of the default credentials cache. The kinit
command overwrites the contents of the alternative cache with
the current credentials.
The name of the default credentials cache may vary between
systems. However, if the KRB5CCNAME logical name is set,
its value is used to name the default cache.
-f Requests the FORWARDABLE option. This option allows a ticket-
granting ticket with a different network address than the
present ticket-granting ticket to be issued to the principal.
For forwardable tickets to be granted, the principal's account
in the registry must specify that the principal can be granted
forwardable tickets.
-l lifetime
Specifies the lifetime of the ticket-granting ticket in hours.
If this option is not specified, the default ticket lifetime
(set by each site using the rgy_edit command) is used.
-p Requests the PROXIABLE option. This option allows a ticket
with a different network address than the present ticket to
be issued to the principal. For proxiable tickets to be
granted, the principal's account in the registry must specify
that the principal can be granted proxiable tickets.
-r lifetime
Requests the RENEWABLE option. This option allows the tickets
issued to the principal to be renewed. For renewable tickets
to be granted, the principal's account in the registry must
specify that the principal can be granted renewable tickets.
The lifetime of the ticket-granting ticket is specified in
hours by lifetime.
-v Specifies that the command should run in verbose mode.
ARGUMENTS
principal
The principal argument specifies the name of the principal
for whom the ticket-granting ticket should be obtained. If
principal is omitted, the principal name from the existing
cache is reused.
DESCRIPTION
The kinit command can be used to refresh a DCE credentials cache. When
you invoke kinit, it prompts for your password.
The ticket lifetime and renewable lifetime are set in the following
format:
{num {interval}}...
where:
num A number that specifies the number of the interval; interval
can be specified by the following:
+
w - weeks
+
d - days
+
h - hours
+
m - minutes
+
s - seconds
For example, to set the lifetime to 3 weeks, 5 days, and 10 hours, the
entry would be the following:
3w5d10h
FILES
dce$local:[var.security.creds]DCECRED*
If the KRB5CCNAME logical name is not set, the
name of the file is in the form shown. If the
KRB5CCNAME logical name is set, its setting
determines the name of the file.
RELATED INFORMATION
COMMANDS: klist
kdestroy
1.6 – klist
NAME
klist - Lists cached tickets
SYNOPSIS
klist [-c cachename] [-e] [-f]
OPTIONS
-c cachename
Specifies that the contents of the cache identified by
cachename should be displayed instead of the contents of
the default cache.
-e Includes expired tickets in the display. Without this
option, only current tickets are displayed.
-f Displays option settings on the tickets. The options are
+
D (postdatable)
+
d (postdated) F (forwardable)
+
f (forwarded)
+
I (initial)
+
i (invalid)
+
P (proxiable)
+
p (proxy)
+
R (renewable)
DESCRIPTION
The klist command lists the primary principal and tickets held in the
default credentials cache, or in the cache identified by cachename if
the -c option is used.
The name of the default credentials cache can vary between systems. How-
ever, if the KRB5CCNAME logical name is set, its value is used to name
the default cache. If it is not set, the form of the name is
dce$local:[var.security.creds]DCECRED*.
RELATED INFORMATION
COMMANDS: kinit
kdestroy
krb5
1.7 – DCE$EXPORT
The DCE EXPORT utility allows you to create an OpenVMS authorization file from an existing DCE registry. The DCE registry entries (or a subset of the registry entries) are converted into records in the OpenVMS SYSUAF file and rights database. Conversions are essentially a reversal of those made with the IMPORT function. Passwords cannot be exported. Instead, the automatic synchronization feature that occurs during integrated login is used to export user pass- words. The DCE EXPORT utility also creates and maintains an exclude list. The exclude list contains the DCE names of users who do not have, and do not require, an OpenVMS account. This feature allows DCE EXPORT to skip over these users during EXPORT operations. NOTE: The DCE EXPORT utility described in this section cannot be satisfied by the export function shipped with OSF DCE because of substantial differences between OpenVMS and UNIX user registry data.
1.7.1 – File Info
The DCE EXPORT utility is shipped as an OpenVMS executable image named DCE$EXPORT.EXE. The image resides in the SYS$SYSTEM directory. The DCE EXPORT exclude file is named by default DCE$EXPORT_EXCLUDE.DAT and also resides in SYS$SYSTEM. You can change the name or location, or both, of this file by defining the logical name DCE$EXPORT_EXCLUDE to point to the new filename and location.
1.7.2 – Running EXPORT
The DCE EXPORT utility allows system administrators to create an
OpenVMS authorization file from an existing DCE registry.
Integrated Login provides two methods of running the DCE EXPORT
utility, as follows.
o By invoking the DCE EXPORT utility using a predefined symbol.
$ EXPORT
EXPORT>
You can also specify a single DCE EXPORT command on the command line.
Control returns to DCL after the command is executed.
$ EXPORT command
$
SYS$COMMON:[SYSMGR]DCE$DEFINE_REQUIRED_COMMANDS.COM defines the DCE
symbol EXPORT, which is used to invoke the DCE EXPORT utility. If
this symbol is not defined in your environment, you can define the
symbol as follows:
$ EXPORT :== $SYS$SYSTEM:DCE$EXPORT
o By issuing the RUN command.
$ RUN SYS$SYSTEM:DCE$EXPORT
EXPORT>
See the HP DCE for OpenVMS Alpha and OpenVMS I64 Reference Guide
for detailed descriptions of the EXPORT commands.
1.7.3 – Messages
1.7.3.1 – EXP_ACCEXISTS
OpenVMS account for <principal> already exists
Explanation:
Could not export <principal> because it has already been
exported.
User Action:
None.
1.7.3.2 – EXP_ADDDCEACC
account for <principal> successfully added to OpenVMS
Explanation:
An OpenVMS acount was successfully created for <principal>.
User Action:
Note directly preceding and following messages for warnings.
1.7.3.3 – EXP_ADDDCEUAF
principal <principal> successfully added to DCE$UAF
Explanation:
Principal <principal> successfully added to the DCE$UAF file
as part of the EXPORT operation. Message displayed only if
/INFORM is specified on the EXPORT command line.
User Action:
None.
1.7.3.4 – EXP_ADDUAF
principal <principal> successfully exported to OpenVMS
Explanation:
An OpenVMS account for successfully created for DCE
<principal>.
User Action:
Note directly preceding and following messages for warnings.
1.7.3.5 – EXP_BINDERR
error binding to DCE security registry
Explanation:
Cannot connect to the DCE security server.
User Action:
Note accompanying error message for more details.
1.7.3.6 – EXP_CREDCEUAF
created new DCE$UAF file
Explanation:
A new DCE$UAF file was created.
User Action:
None.
1.7.3.7 – EXP_DCEERR
<DCE error message>
Explanation:
Accompanying DCE error message.
User Action:
Use this message to solve the problem generating the error.
1.7.3.8 – EXP_DCELOGIN
error in DCE login
Explanation:
Could not perform a DCE login.
User Action:
Enter valid DCE principal and password combination.
1.7.3.9 – EXP_DCEUAFERR
error searching DCE$UAF
Explanation:
Error searching or reading DCE$UAF file.
User Action:
Note accompanying error message for more details.
1.7.3.10 – EXP_DELDCEUAF
principal <principal> successfully deleted from DCE$UAF
Explanation:
Principal <principal> successfully deleted from DCE$UAF as
part of larger delete operation. Message is displayed only
if /INFORM is specified on the EXPORT command line.
User Action:
None.
1.7.3.11 – EXP_DISUSER
<username> remains DISUSER-ed
Explanation:
OpenVMS account for <username> was successfully created but
could not enable the account.
User Action:
Manually remove the DISUSER flag using the AUTHORIZE
utility.
1.7.3.12 – EXP_ERRACCEXC
error accessing DCE EXPORT exclude file
Explanation:
Could not access DCE EXPORT exclude file.
User Action:
Note accompanying error message for more details.
1.7.3.13 – EXP_ERRADDEXC
error adding principal to DCE EXPORT exclude file
Explanation:
Could not add principal to DCE EXPORT exclude file.
User Action:
Note accompanying error message for more details.
1.7.3.14 – EXP_ERRADDUAF
error adding principal to DCE$UAF file
Explanation:
Could not add principal name to DCE$UAF file.
User Action:
Note accompanying error message for more details.
1.7.3.15 – EXP_ERRCRACC
error creating OpenVMS account for <username>
Explanation:
Could not create an OpenVMS account for <username>.
User Action:
See accompanying error message for more details.
1.7.3.16 – EXP_ERRCRDCEUAF
error creating DCE authorization file
Explanation:
An error occurred while attempting to create the DCE$UAF
file.
User Action:
See accompanying message for details.
1.7.3.17 – EXP_ERRCREUAF
error creating OpenVMS account for <username> - see following
messages
Explanation:
Could not create the OpenVMS account for <username>.
User Action:
Note accompanying error messages for more details.
1.7.3.18 – EXP_ERRDCEUAF
error accessing DCE authorization file
Explanation:
An error occurred while attempting to access the
DCE$UAF file.
User Action:
See accompanying message for details.
1.7.3.19 – EXP_ERRDELEXC
error deleting principal from DCE EXPORT exclude file
Explanation:
Could not delete principal from DCE EXPORT exclude file.
User Action:
Note accompanying error message for more details.
1.7.3.20 – EXP_ERRDELUAF
error deleting principal from DCE$UAF file
Explanation:
Could not delete principal from DCE$UAF file.
User Action:
Note accompanying error message for more details.
1.7.3.21 – EXP_ERRENAUSR
error enabling user <username>
Explanation:
Could not remove DISUSER flag from <username>'s account.
User Action:
Manually remove the flag using the AUTHORIZE utility.
1.7.3.22 – EXP_ERRQUOTA
error assigning disk quota to username <username> - see following
messages
Explanation:
Error(s) occurred while attempting to set up disk
quota for <username>
User Action:
Note the messages following this message.
1.7.3.23 – EXP_ERRSETPW
error setting password for <username>
Explanation:
Could not set password for OpenVMS <username>.
User Action:
Manually set password using the AUTHORIZE utility.
1.7.3.24 – EXP_ERRSPAWN
error spawning subprocess
Explanation:
Error spawning subprocess with the SPAWN command.
User Action:
Check user runtime configuration. Refer to appropriate
OpenVMS documentation for more details.
1.7.3.25 – EXP_ERRSYSUAF
error accessing SYSUAF file
Explanation:
Could not access the SYSUAF file.
User Action:
Note accompanying error message for more details.
1.7.3.26 – EXP_ERRUAFGET
error getting SYSUAF information
Explanation:
Error accessing information in the SYSUAF file.
User Action:
Note accompanying error message for more information.
1.7.3.27 – EXP_EXCADD
principal <principal> added to DCE EXPORT exclude list
Explanation:
Principal <principal> successfully added to the DCE EXPORT
exclude list.
User Action:
None.
1.7.3.28 – EXP_EXCDEL
principal <principal> removed from DCE EXPORT exclude list
Explanation:
Principal <principal> successfully deleted from the
DCE EXPORT exclude list.
User Action:
None.
1.7.3.29 – EXP_EXCLUDED
principal <principal> has been excluded from OpenVMS
Explanation:
Unable to export <principal> because it is on the DCE EXPORT
exclude list. This message is displayed only if /INFORM is
specified on the EXPORT command line.
User Action:
If incorrectly excluded, use DELETE/EXCLUDE to remove it
from the DCE EXPORT exclude list and reexport.
1.7.3.30 – EXP_GRPUICFULL
no member UIC available in specified group
Explanation:
No more members available in the specified group.
User Action:
Use another group UIC if possible.
1.7.3.31 – EXP_INDCEUAF
principal <principal> already in DCE$UAF
Explanation:
Could not add already existing principal name to DCE$UAF.
User Action:
None.
1.7.3.32 – EXP_INEXCLUDE
principal <principal> already in DCE EXPORT exclude file
Explanation:
An attempt was made to add an already existing principal
name to the DCE EXPORT exclude file.
User Action:
None.
1.7.3.33 – EXP_INITERROR
initialization error
Explanation:
Error during initialization phase for DCE EXPORT.
User Action:
Note accompanying error message for more details.
1.7.3.34 – EXP_INITWAIT
initializing.....
Explanation:
DCE EXPORT in initialization phase.
User Action:
None.
1.7.3.35 – EXP_INPREQ
input required!
Explanation:
Input not entered where mandatory.
User Action:
Provide input.
1.7.3.36 – EXP_INTERROR
internal error
Explanation:
Internal error in DCE EXPORT.
User Action:
Note accompanying error message for more details or submit
a Quality Assurance Report (QAR).
1.7.3.37 – EXP_INTINPDEV
internal error opening input device
Explanation:
Error accessing SYS$INPUT.
User Action:
Check user runtime configuration. Refer to appropriate
OpenVMS documentation for more information.
1.7.3.38 – EXP_INVGRPUIC
invalid group UIC
Explanation:
Group UIC entered is invalid (format if value, name if
identifier).
User Action:
Enter valid group UIC.
1.7.3.39 – EXP_INVMEMUIC
invalid member UIC
Explanation:
Member UIC entered is out of range or of invalid format.
User Action:
Enter valid member UIC.
1.7.3.40 – EXP_INVMS
principal <principal> already exported to OpenVMS
Explanation:
A record for <principal> already exists in the DCE$UAF file
indicating that is has already been exported.
User Action:
None.
1.7.3.41 – EXP_INVPASSWD
password validation failed. Please retry
Explanation:
Password validation failed while entering password for the
OpenVMS account to be created.
User Action:
Enter valid password.
1.7.3.42 – EXP_INVPWDLEN
password length must be between <minimum> and <maximum> characters
Explanation:
The user specified password for the OpenVMS account is
outside of the defined range.
User Action:
Specify a password of length between <minimum> and <maximum>
1.7.3.43 – EXP_NAMEINUSE
OpenVMS username <username> already mapped to another DCE
principal
Explanation:
OpenVMS username specified is already associated with another
DCE principal in the DCE$UAF file.
User Action:
Specify a username that is not associated with a DCE princi-
pal. Use the DCE$UAF utility to search the DCE$UAF file for
usernames and associated DCE principal names.
1.7.3.44 – EXP_NODCEUAF
unable to open DCE authorization file
Explanation:
Error occurred while attempting to open the
DCE$UAF file.
User Action:
See accompanying message for details.
1.7.3.45 – EXP_NOEXCUSR
no excluded users
Explanation:
No principal names listed in the DCE EXPORT exclude file.
User Action:
None.
1.7.3.46 – EXP_NOSCHUSR
no principal <principal> in DCE registry
Explanation:
Principal <principal> requested for export does not exist in
the DCE registry.
User Action:
Use valid DCE principal name. Use the DCE tool RGY_EDIT to
view DCE principal names.
1.7.3.47 – EXP_NOSUCHEXC
no such principal in DCE EXPORT exclude file
Explanation:
Requested principal does not exist in DCE EXPORT exclude
file.
User Action:
Use the SHOW/EXCLUDE command to list names in the exclude
file.
1.7.3.48 – EXP_NOSUCHPR
no DCE account <principal>
Explanation:
An attempt was made to export a nonexistent DCE principal.
User Action:
Specify a valid DCE principal name. Use the DCE tool
RGY_EDIT to view the DCE principals.
1.7.3.49 – EXP_NOTINEXC
principal <principal> not in DCE EXPORT exclude file
Explanation:
An attempt was made to access a nonexistent record in the
DCE EXPORT file.
User Action:
Use SHOW/EXCLUDE to see the contents of the exclude file.
1.7.3.50 – EXP_NOVMSUSR
no OpenVMS user <username>
Explanation:
A nonexistent OpenVMS username was specified with the /LIKE
qualifier.
User Action:
Specify a valid OpenVMS username.
1.7.3.51 – EXP_NXTMEMUIC
error finding next available member UIC
Explanation:
Could not find the next available member UIC in the group
specified.
User Action:
Note the accompanying error message for more details.
1.7.3.52 – EXP_OUTOPNERR
error opening alternate output
Explanation:
Could not access file name specified with /OUTPUT qualifier.
User Action:
Note accompanying error message for more details.
1.7.3.53 – EXP_SEEFILE
see file <file name> for error messages
Explanation:
Error(s) occurred while creating the OpenVMS
account but EXPORT was unable to display the error
messages. The user is asked to read the file <file name>
for the error messages.
User Action:
Read the file <file name> for error messages.
1.7.3.54 – EXP_TIMERR
DCE time configuration error
Explanation:
Time configuration is incorrect on the DCE system.
User Action:
Refer to the Troubleshooting chapter in the HP
DCE for OpenVMS Alpha and OpenVMS I64 Product Guide.
1.7.3.55 – EXP_TOOLONG
input for <qualifier> too long
Explanation:
Value of <qualifer> is longer than expected maximum size of
value.
User Action:
Enter a value that is within the valid size range.
1.7.3.56 – EXP_USERERR
error getting input from user
Explanation:
User entered invalid input.
User Action:
Enter valid input.
1.7.4 – ADD
Adds DCE principal names. The ADD command can only be used
with the following qualifier:
o ADD/EXCLUDE Adds a DCE principal name to the EXPORT
exclude list (see /EXCLUDE).
/EXCLUDE
Adds a DCE principal name to the EXPORT exclude list.
Format:
ADD/EXCLUDE PRINCIPAL
Parameters
principal
Specifies the DCE principal name to be added to the EXPORT
exclude list.
If the principal name contains lowercase characters,
spaces, or other special characters, enclose the entire
string in quotes.
1.7.5 – DELETE
Deletes DCE principal names. The DELETE command can only be used
with the following qualifier:
o DELETE/EXCLUDE Deletes a DCE principal name from the EXPORT
exclude list (see /EXCLUDE).
/EXCLUDE
Deletes a DCE principal name from the EXPORT exclude list.
Format:
DELETE/EXCLUDE PRINCIPAL
Parameters
principal
Specifies the DCE principal name to be deleted from the
EXPORT exclude list.
If the principal name contains lowercase characters,
spaces, or other special characters, enclose the entire
string is quotes.
1.7.6 – EXIT
Exits the EXPORT utility. You can also exit EXPORT by
pressing the Ctrl/Z key.
Format:
EXIT
1.7.7 – EXPORT
The EXPORT command is used to create OpenVMS accounts
in the OpenVMS system authorization file (SYSUAF) based on
existing accounts in the DCE registry.
Format:
EXPORT DCE-ACCOUNT-NAME
Qualifiers Defaults
/[NO]ADD_IDENTIFIERS /ADD_IDENTIFIERS
/[NO]CONFIRM
/DCE_LOGIN=(keyword=value[,...])
/[NO]EXCLUDE /NOEXCLUDE
/[NO]INFORM /INFORM
/[NO]INTERACTIVE /INTERACTIVE
/OUTPUT[=output] /OUTPUT=SYS$OUTPUT:
/[NO]RECAP /NORECAP
/[NO]TEST_ONLY /NOTEST_ONLY
/[NO]WILD /WILD
Data Qualifiers Defaults
/[NO]ACCOUNT=account /ACCOUNT=dce-group-name
/DEVICE=device Taken from /LIKE account
/DIRECTORY=directory /DIRECTORY=vms-username
/GROUP_UIC=group_uic
/LIKE=vms-account /LIKE=DEFAULT
/MEMBER_UIC=member_uic Next available within UIC group
/[NO]OWNER=owner /OWNER=dce-principal-name
/PASSWORD=passwd None
/[NO]QUOTA=n /QUOTA=1000
/USERNAME=username /USERNAME=dce-principal-name
1.7.7.1 – Parameters
dce-account-name
Specifies the name of the DCE account that is to be
exported. If the DCE account name contains lowercase
characters, spaces or other special characters then
enclose the name in quotes.
If an asterisk is specified in place of the dce-account-
name then all accounts from the registry are selected.
1.7.7.2 – Qualifiers
/CONFIRM
/CONFIRM
/NOCONFIRM
Controls whether the EXPORT command asks for confirmation
before creating the OpenVMS account.
In interactive mode the default is /CONFIRM. In noninteractive
mode the default is /NOCONFIRM.
/DCE_LOGIN=(keyword=value[,...])
/DCE_LOGIN=(keyword=value[,...])
Provides DCE account details for accounts that are authorized to
read pricipals and accounts from the DCE registry. Valid keywords
for the DCE_LOGIN qualifier are as follows:
Keyword Description
PRINCIPAL The principal name to be used for authentication
purposes when reading accounts and/or
principals from the DCE registry.
If you do not specify a principal with this
qualifier you are prompted for one interactively.
PASSWORD The password associated with the principal
name that was specified by the PRINCIPAL keyword.
If you do not specify a password with this
qualifier you are prompted for one interactively.
If you do not specify a principal or password with this qualifi-
er, you are prompted for them interactively, regardless of
whether or not you are running in interactive mode. This infor-
mation need be entered only once per session, on the first EXPORT
command.Subsequent EXPORT commands within the same session do not
require that you to reenter this information.
If you are an interactive user and you do not specify the
PASSWORD keyword, EXPORT prompts you for your password. The
advantage in this is the password is not echoed and therefore
does not appear on your terminal.
/EXCLUDE
/EXCLUDE
/NOEXCLUDE (default)
Determines whether the DCE account is exported to OpenVMS.
If the DCE account is not exported, the OpenVMS account is not
created and an entry is created in the EXPORT exclude file for
the specified DCE account.
/INFORM
/INFORM (default)
/NOINFORM
Determines whether the user is informed of DCE accounts that
would have been selected for export, but are not selected.
(The reasons that accounts are not selected for export are that
they have already been exported (for example, they have an entry
in the DCE$UAF) or that they exist in the EXPORT exclude file.)
/INTERACTIVE (default)
/INTERACTIVE (default)
/NOINTERACTIVE
Controls whether an interactive or noninteractive export is
performed.
In interactive mode, a series of questions is asked and the
user's responses are used to determine the account details. This
mode is well suited to interactive users.
In noninteractive mode, all input is supplied through the data
qualifiers, and any missing or conflicting data causes the
OpenVMS account to not be created. This mode is well suited to
command files and batch jobs.
Data qualifiers can be specified in interactive mode. In this
case the data they provide is used to provide the default answers
to the relevant questions. All questions are still asked.
/OUTPUT[=output]
/OUTPUT[=output]
Defines where all program output should be written.
The default is SYS$OUTPUT:.
/RECAP
/RECAP
/NORECAP (default)
If /RECAP is specified details of the OpenVMS account are dis-
played before it is actually created. When /CONFIRM is also
specified the account details are displayed immediately before
the confirmation request.
/TEST_ONLY
/TEST_ONLY
/NOTEST_ONLY (default)
If /TEST_ONLY is specified, OpenVMS accounts, identifiers, and
DCE$UAF entries are not created. All other functions operate
normally.
/WILD
/WILD (default)
/NOWILD
Specifies whether or not standard VMS wildcarding is to be
applied to dce-account-name. The default is /WILD which means a
dce-account-name of "SM*" is interpreted as meaning "export any
account starting SM".
If /NOWILD is specified the dce-account-name "SM*" is exported.
1.7.7.3 – Data Qualifiers
1.7.7.3.1 /ACCOUNT=account
/ACCOUNT=account (default)
[NO]ACCOUNT
Specifies the account string for the OpenVMS account (same as
/ACCOUNT in AUTHORIZE). The account is a string of 1 to 8
alphanumeric characters.
If this qualifier is not specified, the DCE account's group name
is used (truncated to 8 characters if necessary).
If no account field is required then specify /NOACCOUNT.
1.7.7.3.2 /DEVICE=device
/DEVICE=device
Specifies the name of the OpenVMS account's default
device at login. The device-name is a string of 1 to 31
alphanumeric characters. If you omit the colon from the
device-name value, a colon is automatically appended.
The default device is copy the device field from the
account specified by the /LIKE qualifier.
1.7.7.3.3 /DIRECTORY=directory
/DIRECTORY=directory
Specifies the default directory name for the DIRECTORY field of
the OpenVMS SYSUAF record. The directory name can be 1 to 63
alphanumeric characters. If you do not enclose the directory name
in brackets, EXPORT adds the brackets for you.
The default directory name is [username] where username is the
OpenVMS account's username.
1.7.7.3.4 /GROUP_UIC=group_uic
/GROUP_UIC=group_uic
Specifies the group part of the UIC for the OpenVMS
account. GROUP_UIC can be specified as an octal
group UIC code or as an existing group UIC identifier.
If specified as an octal number, it must be in the
range 1 to 37776 (octal).
The default is to take the OpenVMS account's ACCOUNT
field, convert it to uppercase, and interpret this as a group
UIC identifier. If such an identifier does not exist then
a similar translation is attempted for the DCE account's
group name. If neither identifiers exist, the group
UIC is derived from the OpenVMS account specified by the
/LIKE qualifier.
1.7.7.3.5 /LIKE=vms-account
/LIKE=vms-account
Specifies an existing OpenVMS account that is to be used
as the basis for the OpenVMS account that is being
created. Any fields not specified on the EXPORT command line, as
well as all quotas, privileges, etc, are inherited from
the /LIKE account.
The default is DEFAULT (as it is in AUTHORIZE).
1.7.7.3.6 /MEMBER_UIC=member_uic
/MEMBER_UIC=member_uic
Specifies the member part of the UIC for the OpenVMS
account. MEMBER_UIC should be specified as an octal
number within the range 0 to 177776 (octal).
The default is to use the first available member UIC
within the group UIC (as specified by /GROUP_UIC). For example,
if the selected group is 150 and that group has members 1,
2, 5 and 6 already defined, then the new uic would be
[150,3].
1.7.7.3.7 /OWNER=owner (default)
/OWNER=owner (default)
/NOOWNER
Specifies the owner string for the OpenVMS account (same
as /OWNER in AUTHORIZE). The owner is a string of 1 to 31
characters.
If this qualifier is not specified, the DCE account's principal
name is used (truncated to 31 characters if necessary).
If no owner field is required, specify /NOOWNER.
1.7.7.3.8 /PASSWORD=passwd
/PASSWORD=passwd
Specifies the password for the OpenVMS account. Passwords
contain from 0 to 32 characters and can include
alphanumeric characters, dollar signs, and underscores.
Passwords are not case-sensitive.
If you do not specify a password, the account is
created without a valid OpenVMS password.
1.7.7.3.9 /QUOTA=quota
/QUOTA=quota (default)
/NOQUOTA
Specifies the disk quota for the device specified by
/DEVICE to be given to the OpenVMS account (if quotas
are enabled on that volume).
The default is 1000 blocks. If quotas are not enabled
on the device specified by /DEVICE, or if /NOQUOTA is
specified, then no quota is given.
1.7.7.3.10 /USERNAME=username
/USERNAME=username
Specifies the username for the OpenVMS account. The
username is a string of 1 to 12 alphanumeric characters
and can contain underscores.
If this qualifier is not specified, the DCE account's principal
name is used (truncated to 12 characters and uppercased).
1.7.8 – SHOW
Displays DCE principal names. The SHOW command can only be used
with the following qualifier:
o SHOW/EXCLUDE Displays DCE principal names in the EXPORT
exclude list (see /EXCLUDE).
/EXCLUDE
Displays DCE principal names in the EXPORT exclude list.
Format:
SHOW/EXCLUDE [PRINCIPAL]
Qualifiers Defaults
/ALL
/OUTPUT=output /OUTPUT=SYS$OUTPUT:
1.7.8.1 – Parameters
principal
Specifies the name of the DCE principal to be displayed
from the EXPORT exclude list. Full OpenVMS wildcarding
is allowed.
If the principal name contains lowercase characters,
spaces, or other special characters, enclose the entire
string is quotes.
If /ALL is on the command line, do not specify a principal
name.
1.7.8.2 – Qualifiers
1.7.8.2.1 /ALL
/ALL
Specifies that all EXPORT exclude entries are to be
displayed. If you do not specify principal, then /ALL is
assumed.
1.7.8.2.2 /OUTPUT=output
/OUTPUT=output
Determines where the output is written.
The default is SYS$OUTPUT:.
1.8 – DCE$IMPORT
The DCE IMPORT utility allows you to create principal and account
entries in a DCE registry based on accounts in an existing OpenVMS
authorization file. It is used for the following purposes:
o To populate the DCE registry when a new DCE cell is first established
o To add entries to an existing DCE registry when a new OpenVMS system
joins an existing DCE cell
o To add entries to an existing DCE registry when new users have
joined an OpenVMS sytem that is already part of an existing DCE cell
The DCE IMPORT utility also creates and maintains an exclude list.
The exclude list contains the OpenVMS usernames of users who do not
have, and do not require, a DCE account. This feature allows DCE IMPORT
to skip over these users during DCE IMPORT operations.
NOTE:
The DCE IMPORT utility described in this section cannot be satisfied
by the import function shipped with OSF DCE because of substantial
differences between OpenVMS and UNIX user registry data.
Passwords cannot be imported. Instead, the automatic synchronization
feature that occurs during integrated login is used to import user
passwords.
See the HP DCE for OpenVMS Alpha and OpenVMS I64 Reference Guide
for detailed descriptions of the DCE IMPORT commands.
RELATED INFORMATION
COMMANDS: DCE$EXPORT
1.8.1 – File Info
The DCE DCE IMPORT utility is shipped as an OpenVMS executable image named DCE$IMPORT.EXE. The image resides in the SYS$SYSTEM directory. The DCE IMPORT exclude file is named by default DCE$IMPORT_EXCLUDE.DAT and also resides in SYS$SYSTEM. You can change the name or location, or both, of this file by defining the logical name DCE$IMPORT_EXCLUDE to point to the new filename and location.
1.8.2 – Running IMPORT
The DCE IMPORT utility allows system administrators to create princi-
pal and account entries in a DCE registry based on accounts in SYSUAF.
Integrated Login provides two methods of running the DCE IMPORT
utility, as follows.
o By invoking the DCE IMPORT utility using a predefined symbol.
$ IMPORT
IMPORT>
You can also specify a single DCE IMPORT command on the command line.
Control returns to DCL after the command is executed.
$ IMPORT command
SYS$COMMON:[SYSMGR]DCE$DEFINE_REQUIRED_COMMANDS.COM defines the DCE
symbol IMPORT which is used to invoke the DCE IMPORT utility. If this
symbol is not defined in your environment, you can define the symbol
as follows:
$ IMPORT :== $SYS$SYSTEM:DCE$IMPORT
o By issuing the RUN command.
$ RUN SYS$SYSTEM:DCE$IMPORT
IMPORT>
1.8.3 – Messages
1.8.3.1 – IMP_ACCEXISTS
account for <principal> already exists in DCE
Explanation:
An attempt has been made to recreate an account for
<principal> in the DCE registry.
User Action:
None. This is a warning indicating that this suboperation
in the IMPORT operation was previously performed.
1.8.3.2 – IMP_ADDDCE
username <username> successfully imported into DCE
Explanation:
A DCE account has been successfully created for OpenVMS
username <username>.
User Action:
None.
1.8.3.3 – IMP_ADDDCEACC
account for <principal> successfully added to DCE
Explanation:
A DCE account was successfully created for <principal>.
User Action:
None. This is an informational message displayed only if
/INFORM is specified on the DCE IMPORT command line.
1.8.3.4 – IMP_ADDDCEPRN
principal <principal> successfully added to DCE
Explanation:
Principal <principal> record successfully created in the
DCE registry.
User Action:
None. This is an informational message displayed only when
/INFORM is specified on the DCE IMPORT command line.
1.8.3.5 – IMP_ADDDCEUAF
username <username> successfully added to DCE$UAF
Explanation:
Username <username> successfully added to the DCE$UAF file.
User Action:
None. This is an informational message displayed only if
/INFORM is specified on the DCE IMPORT command line.
1.8.3.6 – IMP_BINDERR
error binding to DCE security registry
Explanation:
Unable to bind to the DCE security server.
User Action:
Note accompanying DCE error message for more details.
1.8.3.7 – IMP_CREDCEUAF
created new DCE$UAF file
Explanation:
A new DCE$UAF file was created.
User Action:
None.
1.8.3.8 – IMP_DCEERR
<DCE error message>
Explanation:
Accompanying DCE error message supplied with other
DCE IMPORT error messages.
User Action:
Use this message to determine the cause of the problem.
1.8.3.9 – IMP_DCELOGIN
error in DCE login
Explanation:
An error occurred during DCE login.
User Action:
Enter a valid DCE username and password when prompted by
DCE IMPORT.
1.8.3.10 – IMP_DCEUAFERR
error searching DCE$UAF
Explanation:
An error occurred while searching the DCE$UAF file.
User Action:
Note the accompanying error message for more details.
1.8.3.11 – IMP_DELACC
account for principal <principal> deleted from DCE
Explanation:
DCE account for <principal> was deleted from the DCE registry.
This occurs when an atomic IMPORT operation fails during one
of its suboperations. Such failure prompts a backout of all
suboperations successfully performed during this IMPORT
operation. Deleting the account is one such backout operation.
User Action:
None. This is an informational message displayed only when
/INFORM is specified on the DCE IMPORT command line.
1.8.3.12 – IMP_DELDCEUAF
username <username> successfully deleted from DCE$UAF
Explanation:
Username <username> deleted from DCE$UAF file.
User Action:
None. This is an informational message displayed only if
/INFORM is specified on the DCE IMPORT command line.
1.8.3.13 – IMP_DELFRGRP
principal <principal> from group <group>
Explanation:
Principal <principal> was deleted from <group> in the DCE
registry. This occurs when an atomic IMPORT operation fails
during one of its suboperations. Such failure prompts a
backout of all suboperations successfully performed during
this IMPORT operation. Deleting the principal from the group
is one such backout operation.
User Action:
None. This is an informational message displayed only when
/INFORM is specified on the DCE IMPORT command line.
1.8.3.14 – IMP_DELFRORG
principal <principal> deleted from organization <organization>
Explanation:
Principal <principal> was deleted from <organization> in the
DCE registry. This occurs when an atomic IMPORT operation
fails during one of its suboperations. Such failure prompts
a backout of all suboperations successfully performed during
this IMPORT operation. Deleting the principal from the
organization is one such backout operation.
User Action:
None. This is an informational message displayed only when
/INFORM is specified on the DCE IMPORT command line.
1.8.3.15 – IMP_DELPRN
principal <principal> deleted from DCE
Explanation:
Principal <principal> was deleted from the DCE registry.
This occurs when an atomic IMPORT operation fails during one
of its suboperations. Such failure prompts a backout of all
suboperations successfully performed during this IMPORT
operation. Deleting the principal is one such backout
operation.
User Action:
None. This is an informational message displayed only when
/INFORM is specified on the DCE IMPORT command line.
1.8.3.16 – IMP_ERRADDGRP
error adding principal <principal> to group <group>
Explanation:
Could not add <principal> to <group> in the DCE registry.
User Action:
Note the accompanying DCE error message for more details.
1.8.3.17 – IMP_ERRADDORG
error adding principal <principal> to organization <organization>
Explanation:
Could not add <principal> to <organization> in DCE registry.
User Action:
Note the accompanying DCE error message for more details.
1.8.3.18 – IMP_ERRACCEXC
error accessing DCE IMPORT exclude file
Explanation:
Could not access the DCE IMPORT exclude file.
User Action:
Note the accompanying error message for more details.
1.8.3.19 – IMP_ERRADDEXC
adding username to DCE IMPORT exclude file
Explanation:
Could not add the requested username to the DCE IMPORT
exclude file.
User Action:
Note the accompanying error message for more details.
1.8.3.20 – IMP_ERRADDUAF
error adding username to DCE$UAF file
Explanation:
Could not add the imported username to the DCE$UAF file.
User Action:
Note the accompanying error message for more details.
1.8.3.21 – IMP_ERRCRACC
error creating account for <principal>
Explanation:
Could not create a DCE account for <principal>.
User Action:
Note the accompanying DCE error message for more details.
1.8.3.22 – IMP_ERRCRDCEUAF
error creating DCE authorization file
Explanation:
An error occurred while attempting to create the
DCE$UAF file.
User Action:
See accompanying message for details.
1.8.3.23 – IMP_ERRCRPRN
error creating principal <principal>
Explanation:
Could not create a principal in the DCE registry.
User Action:
Note the accompanying DCE error message for more details.
1.8.3.24 – IMP_ERRDCEUAF
error accessing DCE authorization file
Explanation:
An error occurred while attempting to access the
DCE$UAF file.
User Action:
See accompanying message for details.
1.8.3.25 – IMP_ERRDELACC
error deleting account for <principal>
Explanation:
Unable to delete account for <principal> from DCE registry.
User Action:
See accompanying DCE error message for more details.
1.8.3.26 – IMP_ERRDELEXC
error deleting username from DCE IMPORT exclude file
Explanation:
Could not remove requested username from the DCE IMPORT
exclude file.
User Action:
Note the accompanying error message for more details.
1.8.3.27 – IMP_ERRDELFRGRP
error deleting principal <principal> from group <group>
Explanation:
An error occurred while deleting <principal>
from <group> in the DCE registry. This delete operation is
performed if the overall IMPORT operation failed and a
backout of changes applied to the DCE registry is
required.
User Action:
See accompanying DCE message for details.
1.8.3.28 – IMP_ERRDELFRORG
error deleting principal <principal> from organization
<organization>
Explanation:
An error occurred while deleting <principal> from
<organization> in the DCE registry. This delete
operation is performed if the overall IMPORT
operation failed and a backout of changes applied to the
DCE registry is required.
User Action:
See accompanying DCE message for details.
1.8.3.29 – IMP_ERRDELPRN
error deleting principal <principal>
Explanation:
Unable to delete <principal> from DCE registry
User Action:
See accompanying DCE error message for more details
1.8.3.30 – IMP_ERRDELUAF
error deleting username from DCE$UAF file
Explanation:
Could not delete a username from the DCE$UAF file.
User Action:
Note the accompanying error message for more details.
1.8.3.31 – IMP_ERRCHGAUT
error changing account authorization policy
Explanation:
Could not change the DCE account's authorization policy.
User Action:
Note the accompanying DCE error message for more details.
1.8.3.32 – IMP_ERRSPAWN
error spawning sub-process
Explanation:
An error occurred while spawning a subprocess on the SPAWN
command.
User Action:
Refer to appropriate OpenVMS documentation for resolution.
1.8.3.33 – IMP_ERRSYSUAF
error accessing SYSUAF file
Explanation:
Could not access the OpenVMS SYSUAF file.
User Action:
See accompanying OpenVMS or RMS error message for more
details.
1.8.3.34 – IMP_EXCADD
username <username> added to DCE IMPORT exclude list
Explanation:
Username <username> successfully added to the DCE IMPORT
exclude file. A DCE account will not be created for this
username.
User Action:
None.
1.8.3.35 – IMP_EXCDEL
username <username> removed from DCE IMPORT exclude list
Explanation:
Username <username> successfully removed from DCE IMPORT
exclude file. A subsequent IMPORT session could be used to
create a DCE account for this username.
User Action:
None.
1.8.3.36 – IMP_EXCLUDED
username <username> has been excluded from DCE
Explanation:
Username <username> cannot be imported since it has been
excluded from the DCE registry.
User Action:
None. This is an informational message displayed when /INFORM
is specified on the DCE IMPORT command line.
1.8.3.37 – IMP_INDCE
username <username> already imported into DCE
Explanation:
An import operation was attempted on an already imported
OpenVMS username.
User Action:
None. This is an informational message displayed only when
/INFORM is specified on the DCE IMPORT command line.
1.8.3.38 – IMP_INDCEUAF
user <username> already in DCE$UAF
Explanation:
Username <username> already exists in the DCE$UAF.DAT file.
User Action:
None. This is a warning indicating that this suboperation in
the IMPORT operation was previously performed.
1.8.3.39 – IMP_INEXCLUDE
username <username> already in DCE IMPORT exclude file
Explanation:
Username <username> has previously been added to the DCE
IMPORT exclude file.
User Action:
None. This informational message is displayed when an exclude
operation is attempted on an already excluded username and
is displayed only when /INFORM is specified on the DCE
IMPORT command line.
1.8.3.40 – IMP_INTINPDEV
internal error opening input device
Explanation:
Error opening SYS$INPUT.
User Action:
Verify user runtime environment. See to appropriate OpenVMS
documentation for more details.
1.8.3.41 – IMP_INITERROR
initialization error
Explanation:
An error occurred during DCE IMPORT's initialization phase.
User Action:
Note error messages accompanying or directly preceding this
message.
1.8.3.42 – IMP_INITWAIT
initializing.....
Explanation:
DCE IMPORT is in initialization mode.
User Action:
None.
1.8.3.43 – IMP_INVPASSWD
password validation failed. Please retry
Explanation:
The password entered when prompted for a retype does not
match the originally entered password.
User Action:
Enter correct password for original and retype entry.
1.8.3.44 – IMP_INPREQ
input required!
Explanation:
Input not entered where input was mandatory.
User Action:
Provide required input.
1.8.3.45 – IMP_INTERROR
internal error
Explanation:
DCE IMPORT internal error occurred.
User Action:
Contact your support engineer or Submit a Quality Assurance
Report (QAR).
1.8.3.46 – IMP_INVDATETM
invalid date/time
Explanation:
Date/time entered has invalid format.
User Action:
Enter date/time in standard format (dd-MMM-yyyy hh:mm:ss).
1.8.3.47 – IMP_NODCEUAF
unable to open DCE authorization file
Explanation:
Error occurred while attempting to open the DCE$UAF file
User Action:
See accompanying message for details.
1.8.3.48 – IMP_NOEXCUSR
no excluded users
Explanation:
No users listed in DCE IMPORT exclude file.
User Action:
None.
1.8.3.49 – IMP_NOGRP
group name not specified
Explanation:
Mandatory qualifier /GROUP not specified during a noninter-
active IMPORT session.
User Action:
Provide the /GROUP qualifier with the group name on the
command line.
1.8.3.50 – IMP_NOORG
organization name not specified
Explanation:
Mandatory qualifier /ORGANIZATION not specified during a
noninteractive IMPORT session.
User Action:
Provide the /ORGANIZATION qualifier with the organiation
name on the command line.
1.8.3.51 – IMP_NOPRIN
principal <principal> does not exist in DCE Registry
Explanation:
Principal <principal> does not exist in the DCE Registry.
This means that <principal> does not have a corresponding
OpenVMS username/account.
User Action:
None.
1.8.3.52 – IMP_NOSUCHEXC
no such username in exclude file
Explanation:
Username specified does not exist in DCE IMPORT's exclude
file.
User Action:
Specify username that exists in DCE IMPORT's exclude file.
Enter command SHOW/EXCLUDE to display the entire exclude
list.
1.8.3.53 – IMP_NOSUCHGRP
no group <group>. Please choose a valid group
Explanation:
The group name specified is nonexistent in the DCE registry.
User Action:
Choose a valid group name. Use the DCE tool RGY_EDIT to
search the DCE registry for group names.
1.8.3.54 – IMP_NOSUCHORG
no organization <organization>. Please choose a valid organization
Explanation:
The organization name specified is nonexistent in the DCE
registry.
User Action:
Choose a valid organization name. Use the DCE tool RGY_EDIT
to search the DCE registry for organization names.
1.8.3.55 – IMP_NOSCHPRM
corresponding primary principal not found in DCE
Explanation:
The DCE principal name specified as the primary principal
while attempting to create an alias principal name is non-
existent in the DCE registry.
User Action:
Use the correct DCE principal name. Use the DCE tool RGY_EDIT
to view the DCE registry.
1.8.3.56 – IMP_NOSCHUSR
OpenVMS username <username> does not exist on this system
Explanation:
An attempt was made to import a nonexistent OpenVMS user.
User Action:
Choose a valid OpenVMS user.
1.8.3.57 – IMP_OUTOPNERR
error opening alternate output
Explanation:
Could not access output medium
User Action:
If /OUTPUT was specified, verify the file name supplied with
/OUTPUT. If /OUTPUT was not specified, check user runtime
environment. See appropriate OpenVMS documentation for more
details.
1.8.3.58 – IMP_PREXISTS
principal <principal> already exists in DCE
Explanation:
An attempt has been made to add <principal> to the DCE
registry.
User Action:
None. This is a warning indicating that this suboperation in
the IMPORT operation was previously performed.
1.8.3.59 – IMP_PRINGRP
principal <principal> already exists in group <group>
Explanation:
An attempt was made to add <principal> to DCE group <group>
when it already was a member of the group. This action was
attempted during an import operation.
User Action:
None. This is an informational message displayed only when
/INFORM is specified on the DCE IMPORT command line.
1.8.3.60 – IMP_PRINORG
principal <principal> already exists in organization <organization>
Explanation:
An attempt was made to add <principal> to DCE organization
<organization> when it was already a member of that
organization. This action was attempted during an import
operation.
User Action:
None. This is an informational message displayed only when
/INFORM is specified on the DCE IMPORT command line.
1.8.3.61 – IMP_PRINUSE
principal <principal> in use by another OpenVMS username
Explanation:
The DCE principal name specified for the OpenVMS username
being imported is associated with another OpenVMS username.
User Action:
Choose a DCE principal name that is not associated with any
OpenVMS username.
1.8.3.62 – IMP_RANGEERR
error in entry! Number must be between 1 and 65535
Explanation:
The value entered for quota is not within the desired range.
User Action:
Enter a number between 1 and 65535.
1.8.3.63 – IMP_TIMERR
DCE time configuration error
Explanation:
Time configuration incorrect on the DCE system.
User Action:
Refer to the Troubleshooting chapter in the HP DCE for
OpenVMS Alpha and OpenVMS I64 Product Guide.
1.8.3.64 – IMP_TOOLONG
input for <qualifier> too long
Explanation:
Value of <qualifer> is longer than expected maximum size of
value.
User Action:
Enter a value that is within the valid size range.
1.8.3.65 – IMP_USERERR
error getting input from user
Explanation:
Error occurred while getting user input.
User Action:
Provide valid input.
1.8.4 – ADD
Adds OpenVMS usernames. The ADD command can only be used
with the following qualifier:
o ADD/EXCLUDE Adds an OpenVMS username to the IMPORT
exclude list (see /EXCLUDE).
/EXCLUDE
Adds an OpenVMS username to the IMPORT exclude list.
Format:
ADD/EXCLUDE USERNAME
Parameters
username
Specifies the name of the OpenVMS account to be added to
the IMPORT exclude list.
1.8.5 – DELETE
Deletes OpenVMS usernames. The DELETE command can only be used
with the following qualifier:
o DELETE/EXCLUDE Deletes an OpenVMS username from the IMPORT
exclude list (see /EXCLUDE).
/EXCLUDE
Deletes an OpenVMS username from the IMPORT exclude list.
Format:
DELETE/EXCLUDE USERNAME
Parameters
username
Specifies the name of the OpenVMS account to be deleted
from the IMPORT exclude list.
1.8.6 – EXIT
Exits the IMPORT utility. You can also exit IMPORT by
pressing the Ctrl/Z key.
Format:
EXIT
1.8.7 – IMPORT
The IMPORT command is used to create DCE accounts based on
OpenVMS accounts from an existing System Authorization File
(SYSUAF).
Format:
IMPORT VMS-USERNAME
Qualifiers Defaults
/[NO]CONFIRM
/DCE_LOGIN=(keyword=value,...)
/[NO]IMPORT /IMPORT
/[NO]EXCLUDE /NOEXCLUDE
/[NO]INFORM /INFORM
/[NO]INTERACTIVE /INTERACTIVE
/MY_PASSWORD=passwd None
/OUTPUT[=output] /OUTPUT=SYS$OUTPUT:
/[NO]RECAP /NORECAP
/[NO]TEST_ONLY /NOTEST_ONLY
Data Qualifiers Defaults
/[NO]EXPIRATION_DATE=d /NOEXPIRATION_DATE
/FLAGS=flags
/GOOD_SINCE_DATE=date /GOOD_SINCE_DATE=now
/GROUP=group "none"
/HOME_DIRECTORY=string None
/LIFETIME=hours Taken from registry authorization
policy
/LOGIN_SHELL=string None
/MISCELLANEOUS=string None
/ORGANIZATION=organiza "none"
/PASSWORD=passwd No valid password
/PRINCIPAL=principal
/RENEWABLE_LIFETIME=ho Taken from registry authorization
policy
1.8.7.1 – Parameters
vms-username
Specifies the name of the OpenVMS account that is to be
imported.
If an asterisk is specified in place of the vms-username,
all accounts from the OpenVMS system authorization
file are selected.
1.8.7.2 – Qualifiers
1.8.7.2.1 /CONFIRM
/CONFIRM
/NOCONFIRM
Controls whether the IMPORT command asks for confirmation
before creating a DCE principal or account, or both.
In interactive mode the default is /CONFIRM. In non-
interactive mode the default is /NOCONFIRM.
1.8.7.2.2 /DCE_LOGIN=(keyword=valud[,...])
/DCE_LOGIN=(keyword=valud[,...])
Provides DCE account details for accounts that are authorized to
create pricipals and accounts in the DCE registry. Valid keywords
for the DCE_LOGIN qualifier are as follows:
Keyword Description
PRINCIPAL The principal name to be used for
authentication purposes when creating
accounts and/or principals in the DCE
registry.
If you do not specify a principal with this
qualifier you are prompted for one
interactively.
PASSWORD The password associated with the principal
name that was specified by the PRINCIPAL
keyword.
If you do not specify a password with this
qualifier you are prompted for one
interactively.
If you do not specify a principal or password with this
qualifier, you are prompted for them interactively, regardless
of whether or not you are running in interactive mode. This
information need be entered only once per session, on the first
IMPORT command. Subsequent IMPORT commands within the same
session do not require you to reenter this information.
If you are an interactive user and you do not specify the
PASSWORD keyword, IMPORT prompts you for your password. The
advantage in this is the password is not echoed and therefore
does not appear on your terminal.
1.8.7.2.3 /EXCLUDE
/EXCLUDE
/NOEXCLUDE (default)
Determines whether or not the OpenVMS account is imported
to the DCE registry. If the OpenVMS account is not imported
then the DCE account is not created and instead an entry
is created in the IMPORT exclude file for the specified
OpenVMS account.
1.8.7.2.4 /INFORM
/INFORM (default)
/NOINFORM
Determines whether or not the user is informed of OpenVMS
accounts that would have been selected for import, but are
not because they either have already been imported (for example,
they have an entry in the DCE$UAF) or they have an entry in
the IMPORT exclude file.
1.8.7.2.5 /INTERACTIVE
/INTERACTIVE (default)
/NOINTERACTIVE
Controls whether an interactive or noninteractive import
is performed.
In interactive mode, a series of questions is asked and the
user's responses are used to determine the account details.
This mode is well suited to interactive users.
In noninteractive mode, all input is supplied through the data
qualifiers, and any missing or conflicting data causes
the DCE account to not be created. This mode is well suited
to command files and batch jobs.
Data qualifiers can be specified in interactive mode.
In this case the data they provide is used to provide the
default answers to the relevant questions. All questions
are still asked.
1.8.7.2.6 /MY_PASSWORD=passwd
/MY_PASSWORD=passwd
DCE requires that you specify your current DCE password
for authentication purposes. If you do not specify your
DCE password with this qualifier you are prompted for
it interactively, regardless of if you are running in
interactive mode or not.
Omitting this qualifier and allowing IMPORT to prompt you
for your DCE password has the advantage that in this case
the password is not echoed and does therefore not appear on
your terminal if you are an interactive user.
OUTPUT[=output]
/OUTPUT[=output]
Defines where all program output should be written.
The default is SYS$OUTPUT:.
1.8.7.2.7 /RECAP
/RECAP
/NORECAP (default)
If /RECAP is specified details of the DCE account are
displayed before it is actually created. When /CONFIRM
is also specified the account details are displayed
immediately before the confirmation request.
1.8.7.2.8 /TEST_ONLY
/TEST_ONLY
/NOTEST_ONLY (default)
If /TEST_ONLY is specified, DCE accounts and DCE$UAF
entries are not created. All other functions operate normally.
1.8.7.3 – Data Qualifiers
1.8.7.3.1 /EXPIRATION_DATE=date
/EXPIRATION_DATE=date
/NOEXPIRATION_DATE (default)
Specifies the expiration date for the DCE account.
If not specified, or if /NOEXPIRATION_DATE is specified,
then the DCE account is created without an expiration date.
1.8.7.3.2 /FLAGS=([no]keyword[,...])
/FLAGS=([no]keyword[,...])
Specifies several attributes of the DCE account. The
keywords you can specify are:
Keyword Description
ACCOUNT_VALID A flag that is set to determine account
validity. An account without this flag set
is invalid and cannot log in.
The default is ACCOUNT_VALID.
CLIENT A flag that is set to indicate whether or
not the account is for a principal that
can act as a client.
The default is CLIENT.
DUPLICATE_KEYS A flag that is set to determine if tickets
issued to the account's principal can have
duplicate keys.
The default is NODUPLICATE_KEYS.
FORWARDABLE_ A flag that is set to determine whether a
CERTIFICATES new ticket-granting ticket with a network
address that differs from the present
ticket-granting ticket network address can
be issued to the account's principal. (The
Proxiable Certificate Flag performs the
same function for service tickets.)
The default is FORWARDABLE_CERTIFICATES.
PASSWORD_VALID A flag that is set to determine whether
the current password is valid. If this
flag is not set, the next time the
principal logs in to the DCE account,
the system prompts the principal to change
his password.
The default is PASSWORD_VALID.
POSTDATED_ A flag that is set to determine if tickets
CERTIFICATES with a start time some time in the future
can be issued to the account's principal.
The default is NOPOSTDATED_CERTIFICATES.
PROXIABLE_ A flag that is set to determine whether or
CERTIFICATE not a new ticket with a different network
address than the present ticket can be
issued to the account's principal. (The
Forwardable Certificate Flag performs
the same function for ticket-granting
tickets.)
The default is NOPROXIABLE_CERTIFICATE.
RENEWABLE_ A flag that is set to determine if the
CERTIFICATE ticket-granting ticket issued to the
account's principal can be renewed.If this
flag is set the authentication service
renews the ticket-granting ticket if its
lifetime is valid.
The default is RENEWABLE_CERTIFICATE.
SERVER A flag that is set to indicate whether or
not the account is for a principal that
can act as a server.
The default is SERVER.
TGT_ A flag that is set to determine whether
AUTHENTICATION or not tickets issued to the account's
principal can use the ticket-granting
ticket authentication mechanism.
The default is TGT_AUTHENTICATION.
1.8.7.3.3 /GOOD_SINCE_DATE=date
/GOOD_SINCE_DATE=date
Specifies the date and time that the account was known to be in
an uncompromised state.
If not specified, the Good Since Date is set to the current date
and time.
1.8.7.3.4 /GROUP=group
/GROUP=group
Specifies the name of an existing DCE group that is
associated with the account being created. Note that if
the group does not exist it is not be created by IMPORT.
The default group name is "none".
1.8.7.3.5 /HOME_DIRECTORY=string
/HOME_DIRECTORY=string
Specifies the directory in which the principal is placed at
login.
If not specified the DCE account is created without a Home
Directory.
1.8.7.3.6 /LIFETIME=hours
/LIFETIME=hours
Specifies the maximum amount of time, in hours, that a
ticket can be valid.
If not specified the Maximum Certificate Lifetime defined
as registry authorization policy is used.
1.8.7.3.7 /LOGIN_SHELL=string
/LOGIN_SHELL=string
Specifies the shell that is executed when a principal logs in.
If not specified the DCE account is created without a login
shell.
1.8.7.3.8 /MISCELLANEOUS=string
/MISCELLANEOUS=string
Specifies a text string that is typically used to describe
the use of the account.
If not specified the DCE account is created without a
miscellaneous value.
1.8.7.3.9 /ORGANIZATION=organization
/ORGANIZATION=organization
Specifies the name of an existing DCE organization that is
associated with the account being created. Note that if the
organization does not exist it is not be created by IMPORT.
The default organization name is "none".
1.8.7.3.10 /PASSWORD=passwd
/PASSWORD=passwd
Specifies the password to be assigned to the DCE account.
If not specified the DCE account is created without a valid
DCE password.
1.8.7.3.11 /PRINCIPAL=(keyword[,...])
/PRINCIPAL=(keyword[,...])
Specifies the principal that is associated with the DCE
account that is being created.
If an existing principal is to be associated with the DCE
account being created then you need only specify NAME (and
ALIAS if its an alias principal). The other keywords are
only used when a new principal is created.
The keywords you can specify are:
Keyword Description
ALIAS Specifies that the principal defined
by the NAME keyword is an alias. By
default the name is considered a primary
principal.
CASE=keyword Specifies how the principal name should be
Formatted. For example, to specify that the
principal name should be all lowercase, use
/PRINCIPAL=CASE=LOWERCASE. Possible
keywords are:
NOEDIT Do not perform any
Format:ting. This is the
default.
LOWERCASE[=n1[,n2]]Convert the principal
name so that the first
n1 characters and last
n2 are lowercase, and the
remainder are uppercase.
If you do not specify
a value for n1 then
the entire principal is
converted to lowercase.
If you do not specify a
value for n2 then 0 is
used.
UPPERCASE[=n1[,n2]]Convert the principal
name so that the first
n1 characters and last
n2 are uppercase, and the
remainder are lowercase.
If you do not specify
a value for n1 then
the entire principal is
converted to uppercase.
If you do not specify a
value for n2 then 0 is
used.
The default is NOEDIT.
FULL_ An optional string that is used to more
NAME=string fully qualify a primary name. If the name
contains spaces, lowercase characters, or
any other special characters, enclose the
string in quotes.
The default is no full name.
NAME=name The standard name (primary or alias) that
is associated with the DCE account. If
the name contains spaces, lowercase
characters, or any other special
characters, enclose the string in quotes.
The default is to take the username
from the system authorization file
(SYSUAF) record, edit it according to
the CASE keyword, and then use this as the
principal name.
OBJECT_ The number of registry objects that can be
CREATION_ created by the principal.
QUOTA=number If you do not specify this keyword then
no quota is established and the principal
can create an unlimited number of registry
objects.
UNIX_ID=number The required UNIX ID that is associated
with the principal.
If a primary principal is being created
you can omit the UNIX ID and one is
generated automatically.
If an alias principal is being created
you must specify the UNIX ID of the
corresponding primary principal.
1.8.7.3.12 /RENEWABLE_LIFETIME=hours
/RENEWABLE_LIFETIME=hours
Specifies the amount of time, in hours, before a
principal's ticket-granting ticket expires and that
principal must log into the system again to reauthenticate
and obtain another ticket-granting ticket.
If not specified the Maximum Certificate Renewable Lifetime
defined as registry authorization policy is used.
1.8.8 – SHOW
Displays OpenVMS usernames. The SHOW command can only be used
with the following qualifier:
o SHOW/EXCLUDE Displays OpenVMS usernames in the IMPORT
exclude list (see /EXCLUDE).
/EXCLUDE
Displays OpenVMS usernames in the IMPORT exclude list.
Format:
SHOW/EXCLUDE [USERNAME]
Qualifiers Defaults
/ALL
/OUTPUT=output /OUTPUT=SYS$OUTPUT:
1.8.8.1 – Parameters
username
Specifies the name of the OpenVMS account to be displayed
from the IMPORT exclude list. Full OpenVMS wildcarding is
allowed.
If /ALL is on the command line, do not specify a username.
1.8.8.2 – Qualifiers
1.8.8.2.1 /ALL
/ALL
Specifies that all IMPORT exclude entries are to be
displayed. If you do not specify username, then /ALL is
assumed.
1.8.8.2.2 /OUTPUT=output
/OUTPUT=output
Determines where the output is written.
The default is SYS$OUTPUT:.
1.9 – rgy_edit
NAME
rgy_edit - Edits the registry database
SYNOPSIS
rgy_edit [[[-a | -p | -g | -o] [-s name] [-up[date]]
[-v [-f] [name | -un[ix__number]] [-nq]] | -l]
OPTIONS
The following options are supplied when rgy_edit is invoked. You can
specify only one of the options -a, -p, -g, and -o. If you specify
the -l option, you can specify no other options.
-a (default)
Edits or views accounts.
-p Edits or views principals.
-g Edits or views groups.
-o Edits or views organizations.
-s Binds to the registry site specified by name. The name
variable is either the fully qualified name of the cell
that contains the registry to which you want access, or
the fully qualified name of a specific registry server.
-up[date] Binds to a read-write registry site in the cell specified
by the -s option.
-v Views the registry entry specified by name or unix_number.
If no entry is specified, all entries are viewed.
-f Displays in full the entry (or entries) selected by the -v
option. The full entry includes all fields except the
membership list and organization policy.
-nq Specifies that delete operations will not be queried. The
default is to prompt the user for verification when a delete
operation is requested.
-l Edits or views entries in local registry.
NOTES
With the exception of the following subcommands, this command is
replaced at Revision 1.1 by the dcecp command. This command may be
fully replaced by the dcecp command in a future release of DCE, and
may no longer be supported at that time.
+ defaults
+ domain
+ scope
+ help
+ quit
+ exit
+ delete
+ purge
+ view
DESCRIPTION
The rgy_edit tool views and edits information in the registry database.
You can invoke rgy_edit from any node.
You can edit and view principals, groups, organization, accounts, and
policies in the network registry (the default) or perform a subset of
those functions on the local registry (using the -l option). Changes
made by rgy_edit apply only to the registry. They do not apply to the
local override file or the local password and group files, both of
which can be edited manually. You can view and change only those
registry objects to which you are granted the appropriate permissions.
INVOKING RGY_EDIT
When you invoke rgy_edit, it displays the following prompt:
rgy_edit=>
At this prompt, you can enter any of the rgy_edit subcommands, and
rgy_edit will prompt you for the required information. Alternatively,
you can enter the subcommand followed by all the options required to
perform a specific operation. The rgy_edit command may prompt you for
any required information you do not enter.
SUBCOMMANDS
In the rgy_edit subcommands that follow, use two double quotation
marks with nothing in between to indicate a null fullname, password,
misc, homedir, or shell. Use double quotation marks to embed spaces,
or hyphens in fullname, misc, and homedir if you specify the argument
on the command line.
1.9.1 – pgo_commands
PRINCIPAL, GROUP, AND ORGANIZATION SUBCOMMANDS Whether name applies to a principal, group, or organization depends on the domain in which you run rgy_edit. Use the do[main] subcommand (described in Miscellaneous Commands) to change domains.
1.9.1.1 – view
v[iew] [name] [-f] [-m] [-po] Views registry entries. The -f option displays entries in full (all fields except the membership list and organization policy). If you are viewing groups or organizations, -m displays the membership list. For principals, -m lists all groups of which the principal is a member, including groups that cannot appear in a project list. If you are viewing organizations, -po displays policy information. If you do not enter the -po option, rgy_edit shows only the organization's name and the UNIX number.
1.9.1.2 – add
a[dd] [principal_name [unix_number] [-f fullname] [-al] [-q quota]] a[dd] [group_name [unix_number] [-f fullname [-nl]]] [-al] ls a[dd] [organization_name [unix_number] [-f fullname]] Create a new name entry. If you do not specify principal_name, group_name, or organization name, the add subcommand prompts you for each field in the entry. If you are adding organizations, the command prompts you for policy information as well. If you specify only principal_name, group_name, or organization_name and no other arguments, the object's fullname defaults to "" (that is, blank), the object's UNIX number is assigned automatically, and the object's creation quota defaults to unlimited. Use the -al option to create an alias for an existing principal or group. No two principals or groups can have the same UNIX number, but a principal or group and all its aliases share the same UNIX number. The -al option creates an alias name for a principal or group and assigns the alias name the same UNIX number as the principal or group. The -q option specifies the principal's object creation quota, the total number of registry objects that can be created by the principal. If you do not specify this option, the object creation quota defaults to unlimited. For groups, the -nl option indicates that the group is not to be included on project lists; omitting this option allows the group to appear on project lists.
1.9.1.3 – change
c[hange] [principal_name [-n name] [-f fullname] [-al | -pr]
[-q quota]]
c[hange] [group_name [-n name] [-f fullname] [-nl | -l] ]
[-al | -pr]
c[hange] [organization_name [-n name] [-f fullname]]
Changes a principal, group, or organization.
Specify the entry to change with principal_name, group_name, or
organization_name. If you do not specify a principal_name,
group_name, or organization_name, the change subcommand prompts
you for a name. If you do not specify any fields, the subcommand
prompts you for each field in succession. To leave a field
unchanged, press <RETURN> at the prompt. If you are changing
organization entries in the interactive mode, the subcommand
prompts you for policy information as well.
Use -n name and -f fullname, to specify a new primary name or
fullname, respectively.
For principals and groups, the -al option changes a primary name
into an alias, and the -pr option changes an alias into a primary
name. This change can be made only from the command line, not in
the interactive mode. The -q option specifies the total number of
registry objects that can be created by the principal.
For group entries, the -nl option disallows the group from
appearing in project lists, while the -l option allows the group
to appear in project lists.
For organization entries, you can change policy information only in
the interactive mode.
Changes to a principal name are reflected in membership lists that
contain the principal name. For example, if the principal ludwig is
a member of the group composers and the principal name is changed
to louis, the membership list for composers is automatically
changed to include louis but not ludwig.
For reserved names, you can change only fullname.
1.9.1.4 – member
m[ember] [group_name | organization_name [-a member_list]
[-r member_list] ]
Edits the membership list for a group or organization.
If you do not specify a group or organization, the member subcommand
prompts you for names to add or remove.
To add names or aliases to a membership list, use the -a option
followed by the names separated by commas. To delete names from a
membership list, use the -r option followed by the names separated
by commas. If you do not include either the -a or -r option on the
command line, rgy_edit prompts you for names to add or remove.
Removing names from the membership list for a group or organization
has the side effect of deleting the login account for removed member
(and, of course, eliminating any permissions granted as a result of
the membership the next time the member's ticket-granting ticket is
renewed).
1.9.1.5 – delete
del[ete] name Deletes a registry entry. If you delete a principal, rgy_edit deletes the principal's account.If you delete a group or organization, rgy_edit deletes any accounts associated with the group or organization. You cannot delete reserved principals.
1.9.1.6 – adopt
adopt uuid principal_name [-u unix_number] [ -f fullname] [-q quota]
adopt uuid group_name [-f fullname] [-nl]
adopt uuid organization_name [-f fullname]
Creates a principal, group, or organization for the specified UUID.
The principal, group, or organization is created to adopt an orphan
object. Orphans are registry objects that cannot be accessed
because 1) they are owned by UUIDs that are not associated with a
principal or group and 2) no other principal, group, or organiza-
tion has access rights to the orphaned object. UUIDs are associ-
ated with all registry objects when the object is created. When
the registry object is deleted, the association between the object
and the UUID is also deleted.
The principal_name, group_name, or organization_name you specify
must be unique in the registry as it must be when you create a
principal, group, or organization using the add subcommand. Except
for the manner in which it is created, the principal, group, or
organization created by the adopt subcommand is no different from
any other principal, group, or organization. The uuid option
specifies the UUID number to be assigned to the principal, group,or
organization. The UUID supplied must be the one that owns the
orphaned object. Specify the uuid in RPC print string format as 8
hexadecimal digits, a hyphen; 4 hexadecimal digits, a hyphen; 4
hexadecimal digits, a hyphen; 4 hexadecimal digits, a hyphen;
and 12 hexadecimal digits. The format follows:
nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn
For cell principals only, the -u option specifies the UNIX number to
be associated with the cell name. If you do not enter this option,
the next sequential UNIX number is supplied as a default. For all
principals other than cells, the UNIX number is extracted from
information embedded in the principal's UUID and cannot be
specified here.
For principals, the -q option specifies the principal's object
creation quota. If you do not enter the option, the object
creation quota is set to "unlimited."
For groups, the -nl option turns off the project list inclusion
property so that groups are not included in project lists. If you
do not enter this option, the group is included in project lists.
For principals, groups, and organizations, the -f option supplies
the object's fullname. If you do not enter the -f option, fullname
defaults to blank.
An error occurs if you specify a name or UNIX number that is
already defined within the same domain of the database.
Note that in the current implementation of the DCE, UNIX numbers
are embedded in UUID numbers. If you try to create a group or
organization to adopt an orphaned object and fail, it could be
because the embedded UNIX number is invalid because it does not
fall within the range of valid UNIX numbers set for the cell as
a registry property. If this is the case, you must reset the
range of valid UNIX numbers to include the UNIX number embedded
in the UUID and then try again to adopt the object.
1.9.2 – account_commands
ACCOUNT SUBCOMMANDS
1.9.2.1 – view
v[iew] [pname [gname [oname]]] [-f]
Displays login accounts.
Without the -f option, view displays only the user fields in each
account entry. These fields include each account's
+ Principal, group, and organization name
+ Encrypted password
+ Miscellaneous information
+ Home directory
+ Login shell
With -f, view displays the full entry, including the adminis-
trative fields as well as the user fields. Administrative
information includes:
+ Who created the account
+ When the account was created
+ Who last changed the account
+ When the account was last changed
+ When the account expires
+ Whether the account is valid
+ Whether the account principal's password is valid
+ When the account principal's password was last changed
1.9.2.2 – add
a[dd] [pname [-g gname -o oname -mp password {-rp | -pw password}
[-m misc] [-h homedir] [-s shell]
[-pnv | -pv] [-x account_exp | none] [-anv | -av]
[ [-ena[ble] option | -dis[able] option]...]
[-gs date_and_time] [-mcr lifespan] [-mcl lifespan]]]
Creates a login account.
If you enter the subcommand only or the subcommand and the optional
pname argument (principal name), rgy_edit prompts you for all
information. If you enter the subcommand, the pname argument, and
the gname (group name) argument or the the pname, gname and oname
(organization name) arguments, you must also enter the -mp, and -pw
or -rp options. All other options are optional.
The pname argument specifies the principal for whom the account
should be created. The -g and -o options specify the account's group
and organization. If the principal specified in pname is not
already a member of the specified group and organization, rgy_edit
automatically attempts to add the principal to the membership lists.
If you do not have the appropriate permissions for the group and
organization, the attempt will fail and the account will not be
created.
The -rp option generates a random password for the account. The
primary use of this option is to create passwords for accounts that
will not be logged into (since the random password can never be
supplied.) The -pw option is used to supply a password for the
account on the command line.
If you use the -rp option or the -pw option, you must also use the
-mp option to supply your password so your identity can be
validated.
If you do not specify the -rp option or the -pw option, rgy_edit
prompts for the account's password twice to ensure you did not make
a typing mistake. Then it prompts for your password to verify your
identity.
If the user's password management policy allows the selection of
generated passwords, specifying "*" as the argument to the -pw
option or at the account's password prompt automatically generates
a plaintext password.
If the user's password management policy requires the selection of
generated passwords, specifying the -pw option is an error.
rgy_edit displays a generated password and then prompts for the
password for confirmation. The format of password must adhere to
the policy of the associated organization or the policy of the
registry as a whole, whichever is more restrictive.
The information supplied with the -m option is used to create the
GECOS field for the account in the /etc/passwd file [on UNIX].
The -h option specifies the pathname of the principal's home
directory. The default homedir is /. The -s option specifies the
pathname of the principal's login shell. The default shell is a
null string.
The -pnv (password not valid) option specifies that the password
has expired. Generally, users must change their passwords when the
passwords expire. However, the policy to handle expired passwords
and the mechanism by which users change their passwords are defined
for each platform, usually through the login facility. The -pv
option indicates the password is not expired (the default).
The -x option sets an expiration date for the account in
yy/mm/dd/hh/mm/ss format. The default is "none," meaning that
the password will never expire.
The -anv (account not valid) option specifies that the account is
not currently valid for login. The -av option indicates the account
is currently valid (the default).
The -enable and -disable options set or clear the following options:
+ The c[lient] option, if enabled, allows the principal to act as
a client and log in, acquire tickets, and be authenticated. If
you disable client, the principal cannot act as a client. The
default is enabled.
+ The s[erver] option, if enabled, allows the principal to act as
a server and engage in authenticated communication. If you
disable server, the principal cannot act as a server that
engages in authenticated communication. The default is enabled.
+ The po[stdated] option, if enabled, allows tickets with a start
time some time in the future to be issued to the account's
principal. The default is disabled.
+ The f[orwardable] option, if enabled, allows a new ticket-
granting ticket with a network address that differs from the
present ticket-granting ticket address to be issued to the
account's principal. The default is enabled.
+ The pr[oxiable] option, if enabled, allows a new ticket with a
different network address than the present ticket to be issued
to the account's principal. The default is disabled.
+ The T[GT_authentication] option, if enabled, specifies that
tickets issued to the account's principal can use the ticket-
granting-ticket authentication mechanism. The default is
enabled.
+ The r[enewable] option turns on the Kerberos V5 renewable
ticket feature. This feature is not currently used by the DCE;
any use of this option is unsupported at the present time.
+ The dup[_session_key] option allows tickets issued to the
account's principal to have duplicate keys. The default is
disabled.
The -gs (good since date) is the date and time the account was last
known to be valid. When accounts are created, this date is set to
the account creation time. If you change the good since date, any
tickets issued before the changed date are invalid. Enter the date
in yy/mm/dd.hh:mm format.
The -mcr (maximum certificate renewable) option is the number of
hours before a session with the principal's identity expires and
the principal must log in again to reauthenticate. The default
is 4 weeks.
The -mcl (maximum certificate lifetime) option is the number of
hours before the Authentication Service must renew a principal's
service certificates. This is handled automatically and requires
no action on the part of the principal. The default is 1 day.
1.9.2.3 – change
c[hange] [-p pname] [-g gname] [-o oname]
[-np pname] [-ng gname] [-no oname]
[{-rp | -pw password} -mp password]
[-m misc] [-h homedir] [-s shell]
[-pnv | -pv] [-x account_exp | none] [-anv | -av]
[[-ena[ble] option | -dis[able] option]...]
[-gs date_and_time] [-mcr lifespan] [-mcl lifespan]
Changes an account.
The -p, -g, and -o options identify the account to change. The -np,
-ng, and -no options change the account's, principal, group, and
organization, respectively.
If you do not specify all three -p, -g, and -o options, wildcard
updates can occur. For example, if you specify only the -g option,
the changes affect all accounts that are associated with the named
group. Note that you cannot use wildcarding to change passwords.
To change a password, you must enter the -p, -g, and -o options.
All other options have the same meaning as described in the add
command for accounts. Note that the -rp option can be used to
change the random passwords of the reserved accounts created by
sec_create_db when the registry database is created.
1.9.2.4 – delete
del[ete] -p pname [-g gname] [-o oname] Deletes the specified account. Enter the -p option to delete the specified principal's account. Enter the -g or -o option to delete accounts associated with the specified group or organization. If you enter the -g or -o option, rgy_edit prompts individually for whether to delete each account associated with the group or organization.
1.9.2.5 – cell
ce[ll] cellname [-ul unix_num] [-uf unix_num] [-gl gname]
[-ol oname] [-gf gname] [-of oname] [-mp passwd]
[-fa name] [-fp passwd] [-q quota]
[-x account_expiration_date | none]
Creates a cross-cell authentication account in the local and
foreign cells.
This account allows local principals to access objects in the
foreign cell as authenticated users and vice versa. The admin-
istrator in the foreign cell must have also set up a standard
account, whose ID and password the administrator of the foreign
cell must supply to you.
The cellname variable specifies the full pathname of the foreign
cell with which you will establish the cross-cell authentication
account. This name is stripped of the path qualifier and prefixed
with "krbtgt." The resulting name is used as the primary name for
the cross-cell authentication account. For example, if you enter
/.../dresden.com, the principal name is krbtgt/dresden.com.
The -ul option specifies the UNIX number for the local cell's
principal. The -uf option specifies the UNIX number for the
foreign cell's principal. If you do not specify these UNIX
numbers, they are generated automatically.
The -gl and -ol options specify the local account's group and
organization. The -gf and -of options specify the foreign
account's group and organization.
The -mp option specifies the password of the person who invoked
rgy_edit.
The -fa option specifies the name identifying the account in the
foreign cell, and the -fp option specifies the account's password.
The -q option specifies the total number of objects that can be
created in your cell's registry by all foreign users who use the
cross-cell authentication account to access your cell. The object
creation quota defaults to 0 (zero), meaning that principals in the
foreign cell cannot create objects in the local cell. The object
creation quota set for your cell's account in the foreign cell
places the same restriction on the number of objects that your
cell's principals can create in the foreign cell's registry.
The -x option specifies the account expiration date for both the
local and foreign accounts. The default for this option is "none."
Note that the object creation quota for the local account defaults
to 0 (zero), meaning that principals in the foreign cell cannot
create objects in the local cell. You can change this with the
rgy_edit change subcommand.
1.9.3 – key_management_commands
KEY MANAGEMENT SUBCOMMANDS The key management subcommands must be run in command-line mode.
1.9.3.1 – ktadd
kta[dd] -p principal_name [-pw password] [-a[uto]] [-r[egistry]]
[-f key-file]
Creates a password for a server or machine in the keytab file on
the local node.
The -p option specifies the name of the server or machine principal
for which you are creating a password.
The -pw option lets you supply the password on the command line. If
you do not enter this option or the -auto option, ktadd prompts for
the password.
The -a option generates the password randomly. If you use this
option, you must also use the -r option. If you do not specify
the -auto or the -pw option, you are prompted for a password.
The -r option updates the principal's password in the registry to
match the string you enter (or automatically generate) for the
password in the keytab file. Use it to ensure that the principal's
password in the registry and the keytab file are in synch when you
change a principal's password in the keytab file. To use this
option, a password for the principal must exist in the default
keytab file or the keytab file named by the -f option.
The -f option specifies the name of the server keytab file on the
local node to which you are adding the password. If you do not
specify a keytab file name, dce$local:[krb5]v5srvtab.; is used.
Note that you must be privileged to add entries in the default
keytab file.
1.9.3.2 – ktlist
ktl[ist] [-p principal_name] [-f keyfile] Displays principal names and password version numbers in the local keytab file. The -p option specifies the name of the server or machine principal for which you are displaying passwords. The -f option specifies the name of the server keytab file on the local node for which you want to display entries. If you do not specify a keytab file name, dce$local:[krb5]v5srvtab.; is used.
1.9.3.3 – ktdelete
ktd[elete] -p principal_name -v version_number [-f keyfile] Deletes a sever or machine principal's password entry from a keytab file. The -p option specifies the name of the server or machine principal for whom you are deleting a password entry. The -v option specifies the version number of the password you want to delete. Version numbers are assigned to a principal's password whenever the principal's password is changed. This allows any servers or machines still using tickets granted under the old pass- word to run without interruption until the ticket expires naturally. The -f option specifies the name of the server keytab file on the local node from which you want to delete passwords. If you do not specify a keytab file name, dce$local:[krb5]v5srvtab.; is used. Note that you must be privileged to delete entries in the default keytab file. You must have the appropriate access rights to delete entries in other keytab files.
1.9.4 – miscellaneous_commands
Miscellaneous Commands
1.9.4.1 – domain
do[main] [p | g | o | a] Changes or displays the type of registry information being viewed or edited. You can specify p for principals, g for groups, o for organizations, or a for accounts. If you supply no argument, rgy_edit displays the current domain.
1.9.4.2 – site
si[te] [[name]] [-u[pdate]] Changes or displays the registry site being viewed or edited. The name variable is the fully qualified name of the cell that contains the registry to which you want access. If you supply no argument, rgy_edit displays the current site. The -update option indicates you want to talk to an update site in the specified cell.
1.9.4.3 – properties
prop[erties] Changes or displays registry properties. This command prompts you for changes. Press <Return> to leave information unchanged.
1.9.4.4 – policy
po[licy] [organization_name] [-al lifespan | forever]
[-pl passwd_lifespan | forever]
[-px passwd_exp_date | none] [-pm passwd_min_length]
[-pa | -pna] [-ps | -pns]
Changes or displays registry standard policy or the policy for an
organization.
Enter organization_name to display or change policy for that
specific organization. If you do not enter organization_name the
subcommand affects standard policy for the entire registry.
The -al option determines the account's lifespan, the period during
which accounts are valid. After this period of time passes, the
accounts become invalid and must be recreated. An account's
lifespan is also controlled by the add and change subcommands -x
option. If the two lifespans conflict, the shorter one is used.
Enter the lifespan in the following in the following format:
weekswdaysdhourshminutesm
For example, 4 weeks and 5 days is entered as 4w5d.
If you enter only a number and no weeks, days, or hours designation,
the designation defaults to hours. If you end the lifepan with a
number and no weeks, days, or hours designation, the number with no
designation defaults to seconds. For example, 12w30 is assumed to
be 12 weeks thirty seconds.
The -pl option determines the password lifespan, the period of time
before account's password expires. Generally, users must change
their passwords when the passwords expire. However, the policy to
handle expired passwords and the mechanism by which users change
their passwords are defined for each platform, usually through the
login facility.
Enter passwd_lifespan as a number indicating the number of days.
If you define a password lifespan as forever, the password has an
unlimited lifespan.
The -px option specifies the password expiration date in
yy/mm/dd/hh.mm:ss format. Generally, users must change their
passwords when the passwords expire. However, the policy to
handle expired passwords and the mechanism by which users change
their passwords are defined for each platform, usually through
the login facility.
If you define a password expiration date as none, the password has
an unlimited lifespan.
The -pm, -ps, -pns, -pa, and -pna options all control the format of
passwords as follows:
+ -pm - Specifies the minimum length of passwords in characters.
If you enter 0, no password minimum length is in effect.
+ -ps and -pns - Specify whether passwords can contain all spaces
(-ps) or can not be all spaces (-pns).
+ -pa and -pna - Specify whether passwords can consist of all
alphanumeric characters (-pn) or must include some non-
alphanumeric characters (-pna).
1.9.4.5 – auth_policy
au[th_policy] Changes and/or displays registry authentication policies. This command prompts you for changes. Press <Return> to leave information unchanged.
1.9.4.6 – defaults
def[aults] Changes or displays the home directory, login shell, password valid option, account expiration date, and account valid option default values that rgy_edit uses. This command first displays the current defaults. It then prompts you for whether or not you want to make changes. If you make changes, defaults immediately changes the defaults for the current session, and it saves the new defaults in sys$login:.rgy_editrc. The newly saved defaults are used until you change them.
1.9.4.7 – help
h[elp] [command Displays usage information for rgy_edit. If you do not specify a particular command, rgy_edit lists the available commands.
1.9.4.8 – quit
q[uit] Exit rgy_edit.
1.9.4.9 – exit
e[xit] Exit rgy_edit.
1.9.4.10 – login
l[ogin] Lets you establish a new network identity for use during the rgy_edit session. The rgy_edit login command prompts for a principal name and password.
1.9.4.11 – scope
sc[ope] [name] Limits the scope of the information displayed by the view subcommand to the directory (specified by name) in the registry database.
1.9.5 – local_registry_commands
Commands for the Local Registry To edit or view the local registry, invoke rgy_edit with the -l option while you are logged into the machine whose local registry you want to maintain. This section lists the commands that are valid for editing or viewing the local registry. When you invoke rgy_edit with the -l option, only the subcommands and options listed here can be used.
1.9.5.1 – view
v[iew] Displays local registry entries.
1.9.5.2 – delete
del[ete] principal_name Deletes the account and credential information for principal_name from the local registry.
1.9.5.3 – purge
pu[rge] Purges expired local registry entries. This command has no options or arguments. The time limit, or lifespan, for which an entry in the local registry is valid is set as a property of the local registry with the properties subcommand. When the purge subcommand is run, it deletes all expired entries. The lifespan begins when an entry for the principal is added to the local registry (that is, the beginning of the lifespan is the last time the principal logged in to the local machine.) The lifespan ends after the time limit set as a local registry property.
1.9.5.4 – properties
pr[operties]
Changes and/or displays local registry properties and policies.
This command displays the current properties and then prompts for
whether you want to make changes to them. You can change the local
registry's:
+ Capacity - A number representing the total number of entries
the local registry can contain at any one time. When the
capacity is reached, subsequent new entries overwrite the
oldest entries.
+ Account lifespan - The time in which an account in the local
registry is valid in the following format:
weekswdaysdhourshminutesm
For example, 4 weeks and 5 days is entered as 4w5d. If you
enter only a number and no weeks, days, or hours designation,
the designation defaults to hours. If you end the lifepan
with a number and no weeks, days, or hours designation, the
number with no designation defaults to seconds. For example,
12w30 is assumed to be 12 weeks thirty seconds.
1.10 – secd
NAME
secd - The DCE Security Server
SYNOPSIS
secd [-b[ootstrap]] [-lockpw] [-locksm[ith]] [pname] [-rem[ote]]
[-master_seqno new_master_seqno] [-cpi time] [-restore_master]
[-v[erbose]]
OPTIONS
-locksm[ith]
Restarts the master Security Server in locksmith mode. Use
this mode if you cannot access the registry as the principal
with full registry access, because that principal's account
has been inadvertently deleted or its password lost.
-pname The pname argument is the name of the locksmith principal. If
no registry account exists for this principal, secd creates
one.
-lockpw Prompt for a new locksmith password when running in locksmith
mode. This option allows you to specify a new password for the
locksmith account when the old one is unknown.
-rem[ote] Allows the locksmith principal to log in remotely. If this
option is not used, the principal must log in from the local
machine on which secd will be started.
-bo[otstrap]
Always waits only one minute between tries to export binding
information to the Cell Directory Service during DCE config-
uration. If you do not specify this option, during initial-
ization secd sleeps for 1 minute if CDS is not available when
it tries to export binding information. If the export fails
a second time, it sleeps for 2 minutes before it tries again.
If it still fails, it sleeps for 4, 8, and 16 minutes between
retries. Then, sleep time stays at 16 minutes until the
binding export succeeds.
-master_seqno
Sets a new master sequence number for the master replica. This
option is used only in unusual situations when a replica that
you want to be the master has a master sequence number that is
lower than (or equal to) another master sequence number in the
system. When the master detects that its master sequence
number is lower than another one in the system, it marks
itself as a duplicate master and its process exits. Each time
you start the master replica, it will notice that it has been
deemed a duplicate master, and its process will again exit.
Use this option to assign a new master sequence number to the
replica you want to be master. The new sequence number should
be one digit higher than the highest master sequence number in
the system. (Use the dcecp registry show -replica command for
each replica to find the highest master sequence number.)
-cpi The checkpoint interval for the mater registry database. This
is the interval in seconds at which the master will read its
database to disk. The default is one hour.
-restore_master
Marks all slave replicas for initialization during the master
restart. Use this option only to recover from a catastrophic
failure of the master security server (for example, if the
database is corrupted and then restored from a backup tape).
-v[erbose]]
Runs in verbose mode.
All options start the Security Server on the local node.
DESCRIPTION
The secd daemon is the Security Server. It manages all access to the
registry database. You must have root privileges to invoke the secd.
The Security Server can be replicated, so that several copies of the
registry database exist on a network, each managed by a secd process.
Only one Security Server, the master replica, can perform database
update operations (such as adding an account). Other servers, the
slave replicas, can perform only lookup operations (such as validating
a login attempt).
A DCE Host daemon (dced) must be running on the local node when secd is
started. Typically, dced and secd are started at boot time. The secd
server places itself in the background when it is ready to service
requests.
LOCKSMITH MODE
The secd -locksmith option starts secd in locksmith mode. The
-locksmith option can be used only with the master replica. In
locksmith mode, the principal name you specify to secd with pname
becomes the locksmith principal. As the locksmith principal, you
can repair malicious or accidental changes that prevent you from
logging in with full registry access privileges.
If no account exists for pname, secd establishes one and prompts you
for the account's password. (Use this password when you log in to the
account as the locksmith principal.) If an account for pname exists,
secd changes the account and policy information as described in the
tables titled "Locksmith Account Changes Made by the Security Server"
and "Registry Policy Changes Made by the Security Server." These
changes ensure that even if account or registry policy was tampered
with, you will now be able to log in to the locksmith account.
In locksmith mode, all principals with valid accounts can log in and
operate on the registry with normal access checking. The locksmith
principal, however, is granted special access to the registry: no
access checking is performed for the authenticated locksmith principal.
This means that, as the locksmith principal, you can operate on the
registry with full access. The following table shows locksmith account
changes that can be made by the security server.
IF THE SECURITY SERVER FINDS IT CHANGES
Password-Valid flag is set to no Password-Valid flag to yes
________________________________________________________________________
Account Expiration date is set to Account Expiration date to
less than the current time plus one the current time plus one
hour hour
________________________________________________________________________
Client flag is set to no Client flag to yes
________________________________________________________________________
Account-Valid flag is set to no Account-Valid flag to yes
________________________________________________________________________
Good Since date is set to greater Good Since date to the
than the current time current time
________________________________________________________________________
Password Expiration date is set Password Expiration date
to less than current time plus to the current time plus
one hour one hour
------------------------------------------------------------------------
The following table shows registry policy changes that can be made by
the security server.
IF THE SECURITY SERVER FINDS IT CHANGES
Account Lifespan is set to Account Lifespan to the
less than the difference current time plus one hour
between the locksmith minus the locksmith
account creation date and account creation date
the current time plus one
hour
_________________________________________________________
Password Expiration date is Password Expiration date
set to greater than the time to the current time plus
the password was last one hour
changed but less than the
current time plus one hour
Use the -lockpw option if the locksmith account exists but you do not
know its password. This option causes secd to prompt for a new lock-
smith password and replace the existing password with the one entered.
Use the -remote option to allow the locksmith principal to log in from
a remote machine.
The secd program normally runs in the background. When you start
secd in locksmith mode, it runs in the foreground so that you can
answer prompts.
EXAMPLES
All of the commands shown in the following examples must be run by a
privileged process:
1. Start a Security Server after you create the database with
sec_create_db.
$ run sys$system:dce$secd
2. Restart an existing replica (master or slave).
$ run sys$system:dce$secd
3. Start the Security Server in locksmith mode and allow the
master_admin principal to log in on a remote machine.
$ secd :== $sys$system:dce$secd.exe
$ secd -locksmith master_admin -remote
1.11 – sec_admin
NAME
sec_admin - Registry replica administration tool
SYNOPSIS
sec_admin [-site name] [-nq]
OPTIONS
-site name
The -site option causes sec_admin to bind to the replica
specified by the name argument. If the option is not
supplied, sec_admin binds randomly to any replica in the
local cell. The name argument can be:
+ A specific cell_name (or /.: for the local cell) to
bind to any replica in the named cell.
+ The global name of a replica to bind to that specific
replica in that specific cell.
+ The name of a replica as it appears on the replica list
to bind to that replica in the local cell.
+ A string binding to a specific replica. An example of a
string binding is ncadg_ip_udp:15.22.144.163. This form
is used primarily for debugging or if the Cell Directory
Service is not available.
-nq The -nq flag turns off queries initiated by certain sec_admin
subcommands before they perform a specified operation. For
example the delrep subcommand deletes a registry replica.
Before sec_admin performs the deletion, it prompts for verifi-
cation. If you invoke sec_admin with the -nq option, the
subcommand performs the deletion without prompting.
NOTES
With the exception of the following subcommands, this command is
replaced at Revision 1.1 by the dcecp command. This command may be
fully replaced by the dcecp command in a future release of DCE, and
may no longer be supported at that time.
+ monitor
+ exit
+ help
+ quit
DESCRIPTION
The registry database is replicated: each instance of a registry server,
secd, maintains a working copy of the database in virtual memory and on
disk. One server, called the master replica, accepts updates and handles
the subsequent propagation of changes to all other replicas. All other
replicas are slave replicas, which accept only queries. Each cell has
one master replica and numerous slave replicas.
Using the sec_admin command you can:
+ View a list of replicas
+ Delete a replica
+ Reinitialize a replica
+ Stop a replica
+ Put the master replica into and out of the maintenance state
+ Generate a new master key used to encrypt principal keys
+ Turn the master registry into a slave registry and a slave registry
into the master registry..
Note that sec_admin cannot add, delete, or modify information in the
database, such as names and accounts. Use rgy_edit to modify registry
database entries.
THE DEFAULT REPLICA AND DEFAULT CELL
Most sec_admin commands are directed to a default replica. When
sec_admin is invoked, it automatically binds to a replica in the local
cell. This replica becomes the default replica.
Identifying the Default Replica and the Default Cell
You use the site subcommand to change the default replica and,
optionally, the default cell. When you use the site command, you can
supply the name of a specific replica, or you can simply supply the
name of a cell. If you supply a cell name, sec_admin binds to a
replica in that cell randomly. If you supply a specific replica name,
sec_admin binds to that replica.
Specifically, you can supply any of the following names to the site
subcommand:
+ A cell name. If you enter a cell name, the named cell becomes the
default cell. The sec_admin command randomly chooses a replica to
bind to in the named cell, and that replica becomes the default
replica.
+ The global name given to the replica when it was created. A global
name identifies a specific replica in a specific cell. That cell
becomes the default cell and that replica the default replica.
+ The replica's name as it appears on the replica list (a list main-
tained by each Security Server containing the network addresses of
each replica in the local cell). That replica becomes the default
replica and the cell in which the replica exists becomes the
default cell.
+ The network address of the host on which the replica is running.
The replica on that host becomes the default replica, and the cell
in which the host exists becomes the default cell.
Naming the Default Replica
As an example, assume a replica named subsys/dce/sec/rs_server_250_2:
+ Exists in the local cell /.../dresden.com
+ Has a global name of /.../dresden.com/subsys/dce/sec/rs_server_250_2
+ Is named subsys/dce/sec/rs_server_250_2 on the replica list
+ Runs on a host whose ip network address is 15.22.144.248
This replica can then be identified to the site subcommand in any of the
following ways:
+ /.../dresden.com/subsys/dce/sec/rs_server_250_2 - The replica's full
global name.
+ subsys/dce/sec/rs_server_250_2 - The replica's cell-relative name on
the replica list.
+ ncadg_ip_udp:15.22.144.248 - The network address of the host on
which the replica runs.
Naming the Default Cell
When a default replica is identified specifically, its cell becomes the
default cell. In the example in "Naming the Default Replica" above, the
default cell is /.../dresden.com.
You can specify simply a cell name to the site subcommand. When this is
done, any replica in that cell is selected as the default replica.
For example, assume
/.../bayreuth.com/subsys/dce/sec/rs_server_300_1
and
/.../bayreuth.com/subsys/dce/sec/rs_server_300_2
are replicas in the cell /.../bayreuth.com.
If you type
site /.../bayreuth.com
then
/.../bayreuth.com
becomes the default cell and either
/.../bayreuth.com/subsys/dce/sec/rs_server_300_1
or
/.../bayreuth.com/subsys/dce/sec/rs_server_300_2
becomes the default replica.
AUTOMATIC BINDING TO THE MASTER
Some of the sec_admin subcommands can act only on the master registry
and thus require binding to the master registry. If you execute a sub-
command that acts only on the master and the master is not the default
replica, sec_admin attempts to bind to the master replica in the
current default cell automatically. If this attempt is successful,
sec_admin displays a warning message informing you that the default
replica has been changed to the master registry. The master registry
will then remain the default replica until you change it with the site
subcommand. If the attempt to bind is not successful, sec_admin
displays an error message, and the subcommand fails.
INVOKING sec_admin
When you invoke sec_admin, it displays the current default replica's
full global name and the cell in which the replica exists. Then it
displays the sec_admin> prompt.
$ sec_admin
Default replica: /.../dresden.com/subsys/dce/sec/music
Default cell: /.../dresden.com
sec_admin>
At the sec_admin> prompt, you can enter any of the sec_admin
subcommands.
SUBCOMMANDS
The subcommand descriptions that follow use default_replica to indicate
the default replica and other_replica to indicate a replica other than
the default. other_replica must identify a replica in the default cell.
It is specified by its name on the cell's replica list (that is, by its
cell-relative name). Use the lrep subcommand to view the default cell's
replica list.
become [ -master ] [ -slave ]
The -master option makes the current default replica (which
must be a slave) the master replica.
The -slave option makes the current default replica (which
must be the master) a slave replica.
This method of changing to master or slave can cause updates
to be lost. The change_master subcommand is the preferred
means of designating a different master replica. However,
you may find the become -master command useful if the master
server is irrevocably damaged and you are unable to use
change_master.
change_master -to other_replica
Make the replica specified by other_replica the master
replica. To perform this operation, other_replica must be
a slave, and the current default replica must be the master.
If the current default replica is not the master, sec_admin
attempts to bind to the master.
If the change operation is successful, the current master:
1. Applies all updates to other_replica
2. Becomes a slave
3. Tells other_replica to become the master
delr[ep] other_replica [-force ]
Delete the registry replica identified by other_replica. To
perform this operation, the current default replica must be
the master. If it is not, sec_admin attempts to bind to the
master.
If the delete operation is successful, the master:
1. Marks other_replica as deleted
2. Propagates the deletion to all replicas on its replica
list
3. Delivers the delete request to other_replica
4. Removes other_replica from its replica list
The -force option causes a more drastic deletion. It causes the master
to first delete other_replica from its replica list and then to
propagate the deletion to the replicas that remain on its list. Since
this operation never communicates with the deleted replica, you should
use -force only when the replica has died irrecoverably. If you use
-force while other_replica is still running, you should then use the
destroy subcommand to eliminate the deleted replica.
h[elp] [command]
Lists the sec_admin subcommands and shows their allowed
abbreviations. If command is specified, displays help for
the specified command.
info [-full]
Displays status information about the default replica.
The info subcommand contacts the default replica to obtain the
appropriate information. If this information is not available,
info prints the replica name and a message stating the
information is not available.
Without the -full option, info displays:
+ The default replica's name and the name of the cell in
which the replica exists
+ Whether the replica is a master or a slave
+ The date and time the replica was last updated and the
update sequence number
+ An indication of the replica's state, as follows:
- Bad State - The state of the replica prohibits the
requested operation.
- Uninitialized - The database is a stub database that
has not been initialized by the master replica or
another up-to-date replica
- Initializing - The replica is in the process of being
initialized by the master replica or another up-to-date
replica
- In Service - The replica is available for queries and
propagation updates if it is a slave replica or queries
and updates if it is the master replica
- Copying Database - The replica is in the process of
initializing (copying its database to) another replica
- Saving Database - The replica is in the process of
saving its database to disk.
- In Maintenance - The replica is unavailable for updates
but will accept queries
- Changing Master Key - The replica is in the process of
having its master key changed
- Becoming Master- The replica is in the process of
becoming the master replica (applicable to slave
replicas only)
- Becoming Slave- The master replica is in the process
of becoming a slave replica (applicable to the master
replicas only)
- Closed - The replica is in the process of stopping
- Deleted - The replica is in the process of deleting
itself
- Duplicate Master - The replica a duplicate master and
should be deleted.
The master replica is available for queries when it is in the
in-service, copying-database, in-maintenance, master-key-
changing and becoming-slave states. It is available for
updates only when it is in the in-service state.
A slave replica is available for queries when it is in the in-
service, copying-database, master-key-changing and becoming-
master states. It accepts updates from the master replica
only when it is in the in-service state. It accepts a request
from the master replica to initialize only when it is in the
uninitialized or in-service state.
The -full option displays all the above information and the following
information:
+ The default replica's unique identifier
+ The replica's network addresses
+ The unique identifier of the cell's master replica
+ The network addresses of the cell's master replica
+ The master sequence number, which is the sequence number
of the event that made the replica the master
+ If the replica is the master replica, the update sequence
numbers that are still in the propagation queue and have
yet to be propagated
+ The DCE software version number.
initr[ep] other_replica
Reinitializes a replica by copying an up-to-date database to
other_replica.
The master replica initiates and guides the operation. If th
operation is successful
1. The master replica
a. Marks other_replica for reinitialization
b. Tells other_replica to reinitialize itself
c. Gives other_replica a list of replicas with
up-to-date databases
2. The other_replica picks a replica from the list and asks
that replica to initialize it (that is, to copy its
database to other_replica)
To perform this operation, other_replica must be a slave, and the
current default replica must be the master. If the current default
replica is not the master, sec_admin attempts to bind to the master.
This subcommand is generally not used under normal conditions.
lr[ep] [-s[tate]] [-u[uid]] [-a[ddr]] [-p[rop]] [-al[l]]
Lists the replicas on the default replica's replica list.
If you enter no options, the display includes the replica name
and whether or not it is the master replica. In addition if
the master replica's list is being displayed, slave replicas
marked for deletion are noted. With options, the display
includes this information and the information described in the
following paragraphs.
The -state option shows each replica's current state, the date
and time the replica was last updated, and the update sequence
number. To obtain this information, lrep contacts each
replica. If this information is not available from the
replica, lrep prints the replica name and a message stating
the information is not available.
The -addr option shows each replica's network addresses.
The -uuid option shows each replica's unique identifier.
The -prop option shows:
+ The date and time of the last update the master sent to
each slave replica
+ The sequence number of the last update to each slave
replica
+ The number of updates not yet applied to each slave replica
+ The status of the master replica's last communication with
each slave replica
+ The propagation state of each slave replica. This state,
illustrates how the master replica views the slave replica,
can be any of the following:
- Bad State-The state of the replica prohibits the
requested operation.
- Marked for Initialization-The replica has been marked
for deletion by the master replica.
- Initialized-The replica has been marked for initializa-
tion by the master replica.
- Initializing-The replica is in the process of being ini-
tialized by the master replica.
- Ready for Updates-The replica has been initialized by
the master replica and in now available for propagation
updates from the master replica.
- Marked for Deletion-The replica has been marked for
deletion by the master replica.
This information is obtained from the master replica; the slave replicas
are not contacted for this information.
The -prop option is valid only for the master.
For slave replicas, the -all option shows all the information above
except that displayed by the -prop option. For the master replica, the
-all option shows all the information.
mas[ter_key]
Generates a new master key for the default replica and re-
encrypts account keys using the new key. The new master key
is randomly generated.
Each replica (master and slaves) maintains its own master key
used to access the data in its copy of the database.
monitor [-r m]
Periodically list the registry replicas stored in the current
default replica's replica list. The list includes each
replica's current state, the date and time the replica was
last updated and the update sequence number. Note that this
is the same information as that displayed by the info sub-
command with no options. The monitor subcommand contacts
each replica to obtain the information it displays. If this
information is not available from the replica, monitor prints
the replica name and a message stating the information is not
available.
The -r option causes the replicas to be listed at intervals
you specify. m is a number of minutes between intervals. The
default is 15 minutes.
destroy default_replica
Destroy the current default replica. To perform this
operation, the current default replica and the default
replica you name as default_replica must be the same. This
is to confirm your desire to perform the deletion.
If the operation is successful, the default replica deletes
its copy of the registry database and stops running. This
subcommand does not delete default_replica from the replica
lists. Use the delrep -force subcommand to delete the replica
from the other replica lists.
The preferred way to delete replicas is to use the delrep
subcommand. However, the destroy subcommand can be used if
delrep is unusable because the master is unreachable or the
replica is not on the master's replica list.
site [name [-u[pdate]]]
Set or display the default cell and the default replica.
The name argument identifies the replica to set as the default
replica and, as a consequence, the default cell. It can be:
+ A specific cell_name (or /.: for the local cell) to make
any replica in the named cell the default.
+ The global name of a replica to make the specified replica
in the specified cell the default.
+ The name of a replica as it appears on the replica list to
make the named replica (which exists in the default cell)
the default replica.
+ A string binding to a specific replica. An example of a
string binding is ncadg_ip_udp:15.22.144.163. This form is
used primarily for debugging or if the Cell Directory
Service is not available.
The -u option specifies that sec_admin should find the master replica.
Normally you specify the name of a cell for name in conjunction with
the -u option. In this case sec_admin finds the master replica in that
cell. If you use a replica name for name, sec_admin queries the named
replica to find the master replica in the named replica's cell.
If you supply no arguments, sec_admin displays the current default
replica and default cell.
stop Stops the Security Server (secd) associated with the default
replica.
sta[te] -maintenance | -service
Puts the master replica into maintenance state or takes it out
of maintenance state. This subcommand is useful for performing
backups of the registry database.
If the current default replica is not the master, sec_admin
attempts to bind to the master.
The -maintenance flag causes the master replica to save its
database to disk and refuse any updates.
The -service flag causes the master replica to return to its
normal "in service" state and start accepting updates.
e[xit] or q[uit]
The quit and exit subcommands end the sec_admin session.
EXAMPLES
1. The following example, invokes sec_admin and uses the lrep sub-
command to list replicas on the replica list and their states:
$ r sys$system:dce$sec_admin
Default replica: /.../dresden.com/subsys/dce/sec/rs_server_250_
Default cell: /.../dresden.com
sec_admin> lrep -st
Replicas in cell /.../dresden.com
(master) subsys/dce/sec/master
state: in service
Last update received at: 1993/11/16.12:46:59
Last update's seqno: 0.3bc
subsys/dce/sec/rs_server_250_2
state: in service
Last update received at: 1993/11/16.12:46:59
Last update's seqno: 0.3bc
subsys/dce/sec/rs_server_250_3
state: in service
Last update received at: 1993/11/16.12:46:59
Last update's seqno: 0.3bc
sec_admin>
2. The following example, sets the default replica to the master in
the local cell:
sec_admin> site /.: -u
Default replica: /.../dresden.com/subsys/dce/sec/master
Default cell: /.../dresden.com
sec_admin>
1.12 – sec_create_db
NAME
sec_create_db - registry database creation utility
SYNOPSIS
sec_create_db {-master | -slave} -my[name] my_server_name
[-cr[eator] creator_name]
[-cu[nix_id] creator_unix_id]
[-g[roup_low_id] g_unix_id]
[-k[eyseed] keyseed]
[-ma[x_unix_id] max_unix_id]
[-o[rg_low_unix_id] o_unix_id]
[-pa[ssword] default_password]
[-p[erson_low_unix_id] p_unix_id]
[-u[uid cell_uuid]
[-v[erbose]]
OPTIONS
{-master | -slave}
Specifies whether the database for the master replica should
be created (-master) or a database for a slave replica should
be created (-slave). All other sec_create_db options can be
used with the -master option. Only the -myname, -keyseed,
and -verbose options can be used with the -slave option.
-my[name] Specifies the name that will be used by the Directory Service
to locate the machine on which the cell's Security Server is
running.
-cr[eator]
Specifies the principal name of the initial privileged user of
the registry database (known as the "registry creator").
-cu[nix_id]
Specifies the UNIX ID of the initial privileged user of the
registry database. If you do not enter the UNIX ID, it is
assigned dynamically.
-g[roup_low_unix_id]
Specifies the starting point for UNIX IDs automatically
generated by the Security Service when groups are added with
the rgy_edit command.
k[eyseed] Specifies a character string used to seed the random key
generator in order to create the master key for the database
you are creating. It should be string that cannot be easily
guessed. The master key is used to encrypt all account pass-
words. Each instance of a replica (master or slave) has its
own master key. You can change the master key using the
sec_admin command.
ma[x] Specifies the highest UNIX ID that can be assigned to a
principal, group, or organization.
-o[rg_low_unix_id]
Specifies the starting point for UNIX IDs automatically
generated by the Security Service when organizations are
added with the rgy_edit command.
-pa[ssword]
The default password assigned to the accounts created by
sec_create_db, including the account for the registry creator.
If you do not specify a default password, -dce- is used.
(Note that the hosts/local_host/self none none,
krbtgt/cell_name none none, and nobody none none accounts are
not assigned the default password, but instead a randomly
generated password.)
-p[erson_low_unix_id]
Specifies the starting point for UNIX IDs automatically
generated by the Security Service when principals are added
with the rgy_edit command.
-u[uid] Specifies the cell's UUID. If you do not enter this UUID, it
is assigned dynamically.
-v[erbose]
Specifies that sec_create_db runs in verbose mode and displays
all activity.
DESCRIPTION
The sec_create_db tool creates new master and slave databases in
DCE$LOCAL:[VAR.SECURITY.RGY_DATA] on the machine from which
sec_create_db is run. Normally, these databases are created only
once by the system configuration tool, dce_config. However, you
can use sec_create_db if you need to re-create the master or a slave
database from scratch. You must be privileged to invoke sec_create_db.
The sec_create_db -master option creates the master database on the
machine on which it is run. This database is initialized with names
and accounts, some of them reserved. You must use the rgy_edit command
to populate the database with objects and accounts.
When the master registry database is created, default ACL entries for
registry objects are also created. These entries give the most
privileged permission set to the principal named in the -cr[eator]
option. If the principal is not one of the reserved names and accounts,
sec_create_db adds it as a new principal and adds an account for that
new principal. If the -cr option is not used, DCE$SERVER is the
creator.
The sec_create_db -slave option creates a slave database on the machine
on which it is run. This command creates a stub database on the local
node in DCE$LOCAL:[VAR.SECURITY.RGY_DATA] and adds the newly created
replica to the master's replica list. The master then marks the replica
to be initialized when a Security Server is started on the slave's node.
The sec_create_db command also creates a registry configuration file,
named DCE$LOCAL:[ETC.SECURITY]PE_SITE.;, that contains the network
address of the machine on which the database is created. This file
supplies the binding address of the secd master server if the Naming
Service is not available.
FILES
DCE$LOCAL:[ETC.SECURITY]PE_SITE.;
The file containing the network address of the machine on
which the security database is created.
DCE$LOCAL:[VAR.SECURITY.RGY_DATA]
The directory in which the registry database files are stored.
1.13 – sec_salvage_db
NAME
sec_salvage_db - Recover a corrupted registry database.
The sec_salvage_db -check and -fix options are not
currently available.
SYNOPSIS
sec_salvage_db -print [-dbpath db_pathname] [-prtpath print_pathname]
[print_options] [-verbose]
sec_salvage_db -reconstruct [-dbpath db_pathname]
[-prtpath print_pathname]
[reconstruct_options] [-verbose]
sec_salvage_db -check [-dbpath db_pathname] [db_options] [-verbose]
sec_salvage_db -fix [-dbpath db_pathname] [db_options] [-force]
[-verbose]
OPTIONS
-check Check the database elements specified by db_options for incon-
sistencies. This option sends a list to standard output of
all bad list links, internal id references, and database keys
and any detectable data inconsistencies. The -check option
does not check fields for legal values.
db_options
Specify the database elements to be acted on by the -check or
-fix options. If no db_options are specified, all are
selected. The db_options are
+ -princ - Principals
+ -group - Groups
+ -org - Organizations
+ -acct - Accounts
+ -acl - ACLs
+ -policy - Policy
+ -state - Database State
+ -replicas - Replicas
The .mkey.prt file and the princ.prt file contain unencrypted
authentication keys. Ensure that only the privileged account can access
these files and that they are never transferred over a network for
viewing or backup.
-fix Check the database for inconsistencies and prompt for whether
to fix each inconsistency. After all inconsistencies have been
processed, the option prompts for whether to save all fixes.
-force Check the database for inconsistencies and fix each one with-
out prompting. After all inconsistencies have been processed,
the option prompts for whether to save all fixes. This
option is valid only when used with the -fix option.
-print Create files containing ASCII-formatted database records.
These files are used by the -reconstruct option as a source
for recreating the database. You can also manually edit the
files to change information or fix problems. A separate file
is created for each of the print_options specified.
By default the -print option stores the master key file in
the current directory and the database files in the rgy_print
directory in the current directory. The -prtpath option lets
you specify a different directory.
print_options
Specify the database elements to be acted on by the -print
option. If the files exist, they are overwritten. If no
print_options are specified, all are selected. The
print_options and the files they create are
+ -princ - Put principal records in the file princ.prt
and master key information in the file
.mkey.prt.
+ -group - Put group records in the file group.prt.
+ -org - Put organization records in the file org.prt.
+ -policy - Put policy records in the file policy.prtt.
+ -state - Put information about the state of the database
in the file rgy_state.prt.
+ -replicas - Put replica information in the file
replicas.prt.
-reconstruct
Reconstruct the registry database from the ASCII-formatted
print files created by the -print option. The
reconstruct_options specify the print files to use.
Specifies which elements of the registry database to re-
construct. If no reconstruct_options are specified, all are
selected. The reconstruct_options are
+ -pgo - Use data in the princ.prt, group.prt, org.prt, and
.mkey.prt files to reconstruct:
- Principals, groups, organizations
- Principal's accounts
- ACL's on database objects
- The master key file
+ -policy - Use data from the policy.prt file to re-
construct registry policies.
+ -state - Use data from the rgy_state.prt file to re-
construct information about the state of the
database.
+ -replicas - Use data from the replicas.prt file to
reconstruct the master replica list.
-dbpath db_pathname
For the -print and -check options, -dbpath specifies the
directory in which the registry database and the master key
file are located. For the -reconstruct and -fix options,
-dbpath specifies the directory in which to store the re-
constructed or salvaged database.
The -print and -check options expects to find the master key
file, .mkey, in the directory above the directory that holds
the database files. For example, if db_pathname is
DCE$LOCAL:[VAR.SECURITY.NEW_RGY], the options look for the
master key file in DCE$LOCAL:[VAR.SECURITY] and the database
files in DCE$LOCAL:[VAR.SECURITY.NEW_RGY].
If this option is not specified, the default pathname is
DCE$LOCAL:[VAR.SECURITY.RGY_DATA].
db_pathname can be a global pathname or a cell-relative name.
-prtpath print_pathname
For the print and -reconstruct options only, -prtpath
specifies the directory in which to create (-print) the print
files, or find (-reconstruct) the print files from which to
reconstruct the database.
By default the -print option creates and the -reconstruct
option looks for the master key file in the current directory
and the database files in the rgy_print subdirectory of the
current directory. The -prtpath option lets you specify the
directory that should be used instead of the current directory.
For example, if you specify print_pathname as
DCE$LOCAL:[VAR.SECURITY.REGISTRY], the master key print file
will be created in that directory and the database print files
in DCE$LOCAL:[VAR.SECURITY.REGISTRY.RGY_PRINT].
If any or all of the print files exist in print_pathname or
the default directory, their contents are overwritten.
print_pathname can be a global pathname or a cell-relative
name.
DESCRIPTION
The sec_salvage_db tool is an aid to database administration and troub-
leshooting. Although day-to-day administration is handled by the
rgy_edit command, sec_salvage_db can be useful for listing registry
data, reconstructing databases, and salvaging corrupted databases.
The sec_salvage_db command supports two methods of operation: the check
and fix method and the print and reconstruct method. These methods can
be used in tandem.
CHECK AND FIX METHOD
The -check and -fix options are not currently available. The check and
fix method recovers data from a corrupted database, fixing corrupted
data links, data retrieval keys, and other internal references. You can
use it on a database so corrupted that it prevents the Security Server
(secd) from running or registry clients from operating correctly. The
check and fix method repairs the database structure so that secd can
run. (Note that data may be lost if corrupted pointers in the registry
data files irreversibly sever the links between records.) The check and
fix method uses the sec_salvage_db -check, -fix, and -force options.
The -check option accesses each record in the database and reports all
errors, but makes no fixes. Although you can run it to see the state of
the database before you run the -fix option, it is not required to be
run.
The -fix option also accesses each record in the database and reports
all errors, but as it finds each error, it prompts for whether or not to
fix the error. When processing is complete, sec_salvage_db prompts for
whether or not to save the changes.
The -force option can only be used with the -fix option. If you use it,
sec_salvage_db does not prompt for confirmation before it fixes each
error it finds. sec_salvage_db will still prompt for confirmation
before it saves the changes.
THE PRINT AND RECONSTRUCT METHOD
The print and reconstruct method allows you to reconstruct a database.
It first creates ASCII files, called print files, that contain all
accessible data in the database. Then, it reads the data in these
files to construct a new database. If you cannot start a Security
Server on the database host machine, you cannot use the print and re-
construct method, but must use the check and fix method. (Note that
before you run sec_salvage_db with the -print and -reconstruct options,
you must stop the Security Server.)
In addition to reconstructing the database, the print and reconstruct
method has other uses. You can use it to
+ Make changes to the database by manually editing the print files
created by the -print option and then reconstructing them from the
changed print files. This can be especially useful for changing
many user passwords, which may be necessary if the master key file
is corrupted.
+ Obtain a listing of database contents.
+ Copy databases between different platforms.
To use the print and reconstruct method run sec_salvage_db first with
the -print option and then with the -reconstruct option.
The -print option creates the ASCII print files from the registry data-
base files. These files can be reviewed and edited to correct faulty
information, such as name-to-UNIX ID mismatches or missing data, or to
update existing data. The -reconstruct option recreates the registry
database files from the print files.
Because the -print option creates files containing all data in the data-
base and the -reconstruct option recreates the database based on these
files, you can use this method to move a database to another machine or
even another cell. For example, if you run sec_salvage_db -print on an
uncorrupted database, you can then run sec_salvage_db -reconstruct and
specify a pathname on a different machine for where the database should
be created.
EDITING THE PRINT FILES
To edit the print files, your entries must be in the following format:
field_name optional_white_space=optional_white_space value
Although you can leave spaces between the field name, the equals sign,
and the value, field names and values cannot contain white space.
A sample org.prt file follows:
Record_Number = 2
Object_Type = ORG
Name = org/none
UUID = 0000000C-D751-21CA-A002-08001E039D7D
Unix_ID = 12
Is_Alias_Flag = false
Is_Required_Flag = false
Fullname =
Member_Name = nobody
Member_Name = root
Member_Name = daemon
Member_Name = uucp
Member_Name = bin
Member_Name = dce-ptgt
Member_Name = dce-rgy
Member_Name = krbtgt/abc.com
Member_Name = hosts/zebra/self
Obj_Acl_Def_Cell_Name = /.../abc.com
Obj_Acl_Entry = unauthenticated:r-t-----
Obj_Acl_Entry = user:root:rctDnfmM
Obj_Acl_Entry = other_obj:r-t-----
Obj_Acl_Entry = any_other:r-t-----
To update existing entries, simply supply a new value. For example, to
update a principal's full name, the entry in the princ.prt file is
Fullname = fullname
The fullname variable is the principal's full name. The princ.prt file
contains the following entry that allows you to update a principal's
password in plain text:
Plaintext_Passwd =
This field does not display the principal's password. To update the
password, simply enter the new one in plain text after the equals sign.
When the database is reconstructed, the password is encrypted and any
keys derived from that password are regenerated and used to overwrite
any existing encryption key entries.
To specify a NULL value, delete the existing value. For example, to
specify a NULL value for a fullname in the princ.prt file, the entry is
Fullname =
PRINT FILE FIELDS AND VALUES
The following lists describe the fields in the princ.prt, group.prt,
org.prt, .mkey.prt, policy.prt, rgy_state.prt, and replicas.prt files.
In the lists, an * (asterisk) indicates a segment or field that can
appear multiple times in succession; a + (plus sign) indicates that if
a stored UUID does not map to a name required for the field, the UUID
is displayed.
THE PRINC.PRT FILE
The fields in the princ.prt file follow:
+ For all records:
Record_Number The sequential number of the record in the database.
Object_Type An indication of the type of object:
PRINC=principal, DIR=directory.
Name Name of the object.
UUID Unique Identifier of the object.
+ For principals:
Unix_ID The principal's Unix ID.
Is_Alias_Flag An indication of whether or not the principal name
is an alias or a primary name: true=alias,
false=primary.
Is_Required_Flag
An indication of whether or not the principal is
reserved: true=principal is reserved and cannot be
deleted, false=principal is not reserved.
Quota The principal's object creation quota: a non-
negative integer or unlimited.
Fullname The principal's fullname: a text string.
Member_Name* The names of the groups to which the principal
belongs.
Obj_Acl_Def_Cell_Name
The default cell name of this principal's object
ACL.
Num_Acl_Entries
The number of entries in the principals object ACL.
Obj_Acl_Entry*+
The contents of the principal's object ACL.
Acct_Group_Name
The account's group name.
Acct_Org_Name The account's organization name.
Acct_Creator_Name
The name of principal who created this account.
Acct_Creation_Time
The date and time the account was created in
yyyy/mm/dd.hh:mm format. The first two digits of
the year, the hours, and the minutes are optional.
Acct_Changer_Name
Name of principal who last changed the account.
Acct_Change_Time
The date and time the account was last changed in
yyyy/mm/dd.hh:mm format. (The first two digits of
the year, the hours and the minutes are optional.)
Acct_Expire_Time
The date and time the account expires or none for no
expiration date. The date and time are in
yyyy/mm/dd.hh:mm format. (The first two digits of
the year, the hours and the minutes are optional.)
Acct_Good_Since_Time
The date and time the principal's account was last
known to be in an uncompromised state in
yyyy/mm/dd.hh:mm, format or no for current time and
date. (The first two digits of the year, the hours
and the minutes are optional.)
Acct_Valid_For_Login_Flag
An indication of whether or not the account can be
logged into: true=account is valid for login,
false=account cannot be logged into.
Acct_Valid_As_Server_Flag
Indicates whether or not the account is a server and
can engage in authenticated communication:
true=account is a server, false=account is not
server.
Acct_Valid_As_Client_Flag
Indicates whether or not the account is a client and
can log in, acquire tickets, and be authenticated:
true=account is a client, false=account is not a
client.
Acct_Post_Dated_Cert_Ok_Flag
Indicates whether or not tickets with a start time
some time in the future can be issued to the
account's principal: true=postdated tickets can be
issued, false=postdated tickets cannot be issued.
Acct_Forwardable_Cert_Ok_Flag
Indicates whether or not a new ticket-granting
ticket with a network address that differs from
the present ticket-granting address can be issued
to the account's principal: true=account can get
forwardable certificates, false=account cannot.
Acct_TGT_Auth_Cert_Ok_Flag
Indicates whether or not tickets issued to the
account's principal can use the ticket-granting-
ticket authentication mechanism: true=tickets can
use the ticket-granting-ticket authentication
mechanism, false=they cannot.
Acct_Renewable_Cert_Ok_Flag
Indicates whether or not tickets issued to the
principal's ticket-granting ticket to be renewed:
true=tickets can be renewed, false=tickets cannot be
renewed.
Acct_Proxiable_Cert_Ok_Flag
Indicates whether or not a new ticket with a
different network address than the present ticket
can be issued to the account's principal: true=such
a ticket can be issued, false=such a ticket cannot
be issued.
Acct_Dup_Session_Key_Ok_Flag
Indicates whether or not tickets issued to the
account's principal can have duplicate keys:
true=account can have duplicate session keys,
false=account cannot.
Unix_Key The account principal's encrypted UNIX password:
ASCII string.
Plaintext_Passwd
Stores the principal's password in plain text. This
field is provided to allow principal's passwords to
be changed. When the princ.prt file is processed by
the sec_salvage_db -reconstruct option, this pass-
word is encrypted using UNIX system encryption. This
encrypted password is then stored as the principal's
encrypted UNIX password in the Unix_Key field.
Home_Dir The account principal's home directory: text string.
Shell The account principal's login shell: text string.
Gecos The account's GECOS information: text string.
Passwd_Valid_Flag
Indicates whether or not the account principal's
password is valid: true=password is valid,
false=password not valid.
Passwd_Change_Time
The date and time the account principal's password
was last changed in yyyy/mm/dd.hh:mm format or now
for the current date and time. The first two digits
of the year, the hours and the minutes are optional.
Max_Certificate_Lifetime
The number of hours before the Authentication
Service must renew the account principal's service
certificates: an integer indicating the time in
hours or default-policy to use the registry default.
Max_Renewable_Lifetime
The number of hours before a session with the
account principal's identity expires and the
principal must log in again to reauthenticate:
an integer indicating the time in hours or
default-policy to use the registry default.
Master_Key_Version
The version of the master key used to encrypt the
account principal's key.
Num_Auth_Keys The number of the account principal's authentication
keys.
Auth_Key_Version*
A list of the version numbers of the account
principal's authentication key. The first version
number on the list represents the current authenti-
cation key.
Auth_Key_Pepper*
The pepper algorithm used for the account
principal's key: a text string or blank to use
the default pepper algorithm.
Auth_Key_Len* The length in bytes of the account principal's
authentication key.
Auth_Key* The account principal's authentication key: hex
string.
Auth_Key_Expire_Time*
The date and time the account principal's authenti-
cation key expires or none for no expiration. Date
and time are in yyyy/mm/dd.hh:mm format. (The first
two digits of the year, the hours and the minutes
are optional.)
+ For directories:
Obj_Acl_Def_Cell_Name+
The default cell name of the directory's object ACL.
Num_Acl_Entries
The number of entries in the directory's object ACL.
Obj_Acl_Entry*+
The contents of the directory's object ACL.
Init_Obj_Acl_Def_Cell_Name+
The default cell name of the directory's initial
object ACL.
Num_Acl_Entries
The number of entries in the directory's initial
object ACL.
Init_Obj_Acl_Entry*+
The contents of the directory's initial object ACL.
Init_Cont_Acl_Def_Cell_Name+
The default cell name of the directory's initial
container ACL.
Num_Acl_Entries
The number of entries in the directory's initial
container ACL.
Init_Cont_Acl_Entry*+
The contents of the directory's initial container
ACL.
THE GROUP.PRT FILE
The fields in the group.prt file follow:
+ For all records:
Record_Number The sequential number of the record in the database.
Object_Type An indication of the type of object: GROUP=group,
DIR=directory.
Name Name of the object.
UUID Unique Identifier of the object.
+ For groups:
Unix_ID Unix ID of the group.
Is_Alias_Flag An indication of whether or not the group name is an
alias or a primary name: true=alias, false=primary.
Is_Required_Flag
An indication of whether or not the group is
reserved: true=group is reserved and cannot be
deleted, false=group is not reserved.
Projlist_Ok_Flag
An indication of whether or not the group can be
included in project lists: true=group can be
included on project lists, false=group cannot be
included.
Fullname The group's fullname: a text string.
Member_Name* The names of the group's members.
Obj_Acl_Def_Cell_Name+
The default cell name of this group's object ACL.
Num_Acl_Entries
The number of entries in the group's object ACL.
Obj_Acl_Entry*:
The contents of the group's object ACL.
+ For directories:
Obj_Acl_Def_Cell_Name+
The default cell name of this directory's object
ACL.
Num_Acl_Entries
The number of entries in the directory's object ACL.
Obj_Acl_Entry* The contents of the directory's object ACL.
Init_Obj_Acl_Def_Cell_Name+
The default cell name of the directory's initial
object ACL.
Num_Acl_Entries
The number of entries in the directory's initial
object ACL.
Init_Obj_Acl_Entry*+
The contents of the directory's initial object ACL.
Init_Cont_Acl_Def_Cell_Name+
The default cell name of the directory's initial
container ACL.
Num_Acl_Entries
The number of entries in the directory's initial
container ACL.
Init_Cont_Acl_Entry*+
The contents of the directory's initial container
ACL.
THE ORG.PRT FILE
The fields in the org.prt file follow:
+ For all records:
Record_Number The sequential number of the record in the database.
Object_Type An indication of the type of object:
ORG=organization, DIR=directory.
Name Name of the object.
UUID Unique Identifier of the object.
+ For organizations:
Unix_ID Unix ID of the organization.
Is_Alias_Flag An indication of whether or not the organization
is an alias or a primary name: true=alias,
false=primary.
Is_Required_Flag
An indication of whether or not the organization is
reserved: true=organization is reserved and cannot
be deleted, false=organization is not reserved.
Fullname The organization's fullname: a text string.
Member_Name* The names of the organization's members.
Obj_Acl_Def_Cell_Name
The default cell name of this organization's object
ACL.
Num_Acl_Entries
The number of entries in the organization's object
ACL.
Obj_Acl_Entry*+
The contents of the organization's object ACL.
+ For organizations with policy:
Acct_Lifetime The period during which accounts for the organiza-
tion are valid: a integer number representing days
or forever.
Passwd_Min_Len The minimum length of the organization's password: a
non-negative integer.
Passwd_Lifetime
The span in days of the lifetime of the organiza-
tion's password: an integer or forever.
Passwd_Expire_Time
The date and time the organization's password
expires in yyyy/mm/dd.hh:mm format. (The first
two digits of the year, the hours and the minutes
are optional.)
Passwd_All_Spaces_Ok
An indication of whether or not the organization's
password can consist of all spaces: true=can consist
of spaces, false=cannot.
Passwd_All_Alphanumeric_Ok
An indication of whether or not the organization's
password can consist of all alphanumeric characters:
true=can be all alphanumeric, false=cannot.
+ For directories:
Obj_Acl_Def_Cell_Name+
The default cell name of the directory's object ACL.
Num_Acl_Entries
The number of entries in the directory's object ACL.
Obj_Acl_Entry*+
The contents of the directory's object ACL.
Init_Obj_Acl_Def_Cell_Name+
The default cell name of the directory's initial
object ACL.
Num_Acl_Entries
The number of entries in the directory's initial
object ACL.
Init_Obj_Acl_Entry*+
The contents of the directory's initial object ACL.
Init_Cont_Acl_Def_Cell_Name+
The default cell name of the directory's initial
container ACL.
Num_Acl_Entries
The number of entries in the directory's initial
container ACL.
Init_Cont_Acl_Entry*+
The contents of the directory's initial container
ACL.
THE .MKEY.PRT FILE
The fields in the .mkey.prt file follow:
Master_Key_Version
The integer version of the master key.
Master_Key_Keytype
Always des.
Master_Key_Length
The length of the master key in bytes.
Master_Key The master key in hex string format.
The policy.prt File
The fields in the policy.prt file follow:
Rgy_Policy_File_Version
An integer representing the version of the policy
information.
Prop_Read_Version
A number indicating the property record's read version.
Prop_Write_Version
A number indicating the property record's write version.
Min_Certificate_Lifetime
The minimum amount of time before the principal's ticket
must be renewed in weekswdaysdhourshminutesm format.
Default_Certificate_Lifetime
The the default lifetime for tickets issued to principals
in this cell's registry in weekswdaysdhourshminutesm
format.
Low_Unix_ID_Principal
The starting point for principal UNIX IDs automatically
generated by the Security Service when a principal is
added: an integer, which must be less than Max_Unix_ID.
Low_Unix_ID_Group
The the starting point for UNIX IDs automatically
generated by the Security Service when a group is
added: an integer, which must be less than Max_Unix_ID.
Low_Unix_ID_Org
The starting point for UNIX IDs automatically generated
by the Security Service when an organization is added
using: an integer, which must be less than Max_Unix_ID.
Max_Unix_ID The highest number that can be supplied as a UNIX ID when
principals are created: an integer.
Rgy_Readonly_Flag
An indication of whether or not the registry is
read-only: true=read only, false=updateable.
Auth_Certificate_Unbound_Flag
An indication of whether or not certificates are
generated for use on any machine: true=yes, false=no.
Shadow_Passwd_Flag
Determines whether encrypted passwords are sent over the
network: true=encrypted passwords are not sent over the
network, false=encrypted passwords are sent over the
network.
Embedded_Unix_ID_Flag
Determines if UNIX IDs are embedded in person, group,
and organization UUIDs: true=UNIX IDs are embedded,
false=UNIX IDs are not embedded.
Realm_Name The name of the full global pathname of realm running the
secd.
Realm_UUID The UUID of the realm running the secd.
Unauthenticated_Quota
The quota of unauthenticated users: a number or
unlimited.
Acct_Lifetime The period during which accounts are valid: a integer
number representing days or forever.
Passwd_Min_Len The minimum length of passwords: a non-negative integer.
Passwd_Lifetime
The span in days of the password lifetimes: an integer or
forever.
Passwd_Expire_Time
The date and time the passwords expire in
yyyy/mm/dd.hh:mm format. (The first two digits of
the year, the hours and the minutes are optional.)
Passwd_All_Spaces_Ok
An indication of whether or not passwords can consist of
all spaces: true=can consist of spaces, false=cannot.
Passwd_All_Alphanumeric_Ok
Am indication of whether or not passwords can consist of
all alphanumeric characters: true=can be all alpha-
numeric, false=cannot.
Max_Certificate_Lifetime
The number of hours before the Authentication Service
must renew service certificates: an integer indicating
the time in hours or default-policy to use the registry
default.
Max_Renewable_Lifetime
The number of hours before sessions expire and the
session principal must log in again to reauthenticate:
an integer indicating the time in hours or default-
policy to use the registry default.
Princ_Cache_State
The timestamp of the principal cache.
Group_Cache_State
The timestamp of the group cache.
Org_Cache_State
The timestamp of the organization cache.
My_Name The cell-relative name of the security server.
Master_Key_Version
The integer version of current master key.
Master_Key_Keytype
Always des.
Master_Key_Length
The length of the master key in bytes.
Master_Key The master key in hex string format.
Old_Master_Key_Version
The version of the previous master key.
Old_Master_Key_Keytype
Always des.
Old_Master_Key_Length:
The length of the previous master key in bytes.
Old_Master_Key:
The previous master key in hex string format.
Obj_Acl_Def_Cell_Name:
The default cell name of the policy object ACL.
Num_Acl_Entries:
The number of entries in the policy object ACL.
Obj_Acl_Entry*+
The contents of the policy object ACL.
The rgy_state.prt File
The fields in the rgy_state.prt file follow:
Rgy_State_File_Version
The integer version number of the format of the rgy_state
file.
Replica_State The state of the master registry: unknown_to_master,
uninitialized, in_service, in_maintenance, closed,
deleted, or initializing.
Cell_UUID The UUID of cell in which the secd resides.
Server_UUID The UUID of this secd.
Initialization_UUID
The UUID of the last initialization event.
Master_File_Version
The version number of the master replica.
Master_Known_Flag
An indicate of whether or not the master replica is known
to this replica: true=known, false=not known. Only if
this field is true do the other master field contain
valid information.
Master_UUID The UUID of the master replica.
Master_Seqno: The 2-digit sequence number of the event when the master
became the master in n.n format.
The replicas.prt File
The fields in the replicas.prt file follow:
Record_Number The sequential number of the record in the database.
Replica_UUID The UUID listed for the replica in the replica list.
Replica_Name The name of the replica as known to the Cell Directory
Service.
Num_Towers The number of towers.
Tower_Length* The Length of the next tower (in bytes).
Tower* The tower used to communicate with the replica (a byte
stream that can be broken on word boundaries).
Propagation_Type
An indication of whether the replica is initialized,
initializing, in the process of being updated, or in
the process of being deleted.
Initialization_UUID
UUID of the last initialization.
ERROR CONDITIONS
You receive the following error message if the default rgy_data
directory is being used and there is an advisory lock on the rgy_state
data file:
Registry: Error - database is locked. Put secd into maintenance
mode or clear advisory lock on rgy_state file in db_pathname
The existence of the advisory lock implies that secd is in service. Use
the sec_admin command to put secd in maintenance mode. If secd is not
running, the advisory lock may be the result of an ungraceful shutdown
of secd. To remove the advisory lock, use the rename command to rename
the DCE$LOCAL:[VAR.SECURITY.RGY_DATA]RGY_STATE.; file, and then change
it back to its original name. Then rerun the sec_salvage_db command.
2 – Admin File
This section describes v5srvtab, a DCE Security file used
for system administration.
NAME
v5srvtab - The server and machine keytab file
DESCRIPTION
The DCE$LOCAL:[KRB5]V5SRVTAB.; file is a file on the local node
created by the rgy_edit command, the sec_create_db command, or any
application that makes sec_key_mgmt() calls. The file contains
passwords for servers and machine accounts. To view or manipulate
the contents of this file, use the sec_key_mgmt API, described in
the OSF DCE Application Development Guide - Core Components and the
OSF DCE Application Development Reference.
RELATED INFORMATION
BOOKS: OSF DCE Application Development Guide - Core Components
OSF DCE Application Development Reference
3 – API Intro
NAME
sec_intro - Application Program Interface to the DCE Security Service
DESCRIPTION
The Distributed Computing Environment (DCE) Security Service Application
Program Interface (API) allows developers to create network services with
complete access to all the authentication and authorization capabilities
of DCE Security Service and facilities.
The transaction of a network service generally consists of a client
process requesting some action from a server process. The client may
itself be a server, or a user, and the server may also be a client of
other servers. Before the targeted server executes the specified action,
it must be sure of the client's identity, and it must know whether the
client is authorized to request the service.
The Security Service API consists of the following sets of Remote
Procedure Calls (RPCs) used to communicate with various security-
related services and facilities:
+ rgy - Maintains the network registry of principal identities.
+ era - Maintains extended registry attributes.
+ login - Validates a principal's network identity and establish
delegated identities.
+ epa - Extracts privilege attributes from an opaque binding handle.
+ acl - Implements an Access Control List (ACL) protocol for the
authorization of a principal to network access and services.
+ key - Provides facilities for the maintenance of account keys for
daemon principals.
+ id - Maps file system names to Universal Unique IDs (UUIDs).
+ pwd_mgmt - Provides facilities for password management.
All the calls in this API have names beginning with the sec_ prefix.
These are the same calls used by various user-level tools provided as
part of the DCE. For example, the sec_create_db tool is written with
sec_rgy calls, acl_edit is written with sec_acl calls, and the login
program, with which a user logs in to a DCE system, is written using
sec_login calls. Most sites will find the user-level tools adequate
for their needs, and only must use the Security Service API to
customize or replace the functionality of these tools.
Though most of the calls in the Security Service API represent RPC
transactions, code has been provided on the client side to handle much
of the overhead involved with making remote calls. These "stubs" handle
binding to the requested security server site, the marshalling of data
into whatever form is needed for transmission, and other bookkeeping
involved with these remote calls. An application programmer can use
the Security Service interfaces as if they were composed of simple C
functions.
This reference page introduces each of the following APIs:
+ Registry APIs
+ Login APIs
+ Extended Privilege Attributes APIs
+ Extended Registry Attributes APIs
+ ACL APIs
+ Key Management APIs
+ ID Mapping APIs
+ Password Management APIs
The section for each API is organized as follows:
+ Synopsis
+ Data Types
+ Constants
+ Files
3.1 – REGISTRY_API_DATA_TYPES
SYNOPSIS
#include <dce/rgybase.h>
DATA TYPES
The following data types are used in sec_rgy_ calls:
sec_rgy_handle_t
A pointer to the registry server handle. The registry server is
bound to a handle with the sec_rgy_site_open() routine.
sec_rgy_bind_auth_info_type_t
A enumeration that defines whether or not the binding is
authenticated. This data type is used in conjunction with the
sec_rgy_bind_auth_info_t data type to set up the authorization
method and parameters for a binding. The
sec_rgy_bind_auth_info_type_t type consists of the following
elements:
+ sec_rgy_bind_auth_none-The binding is not authenticated.
+ sec_rgy_bind_auth_dce-The binding uses DCE shared-secret
key authentication.
sec_rgy_bind_auth_info_t
A discriminated union that defines authorization and authentication
parameters for a binding. This data type is used in conjunction
with the sec_rgy_bind_auth_info_type_t data type to set up the
authorization method and parameters for a binding. The
sec_rgy_bind_auth_info_t data type consists of the following
elements:
info_type A sec_rgy_bind_auth_info_type_t data type that specifies
whether or not the binding is authenticated. The contents of the
union depend on the value of sec_rgy_bind_auth_info_type_t.
For unauthenticated bindings
(sec_rgy_bind_auth_info_type_t = sec_rgy_bind_auth_none),
no parameters are supplied.
For authenticated bindings
(sec_rgy_bind_auth_info_type_t = sec_rgy_bind_auth_dce),
the dce_info structure is supplied.
dce_info A structure that consists of the following elements:
authn_level
An unsigned 32 bit integer indicating the
protection level for RPC calls made using the
server binding handle. The protection level
determines the degree to which authenticated
communications between the client and the
server are protected by the authentication
service specified by authn_svc. If the RPC
runtime or the RPC protocol in the bound
protocol sequence does not support a specified
level, the level is automatically upgraded to
the next higher supported level. The possible
protection levels are as follows:
+ rpc_c_protect_level_default - Uses the
default protection level for the specified
authentication service. The default
protection level for DCE shared-secret key
authentication is
rpc_c_protect_level_pkt_value
+ rpc_c_protect_level_none - Performs no
authentication: tickets are not exchanged,
session keys are not established, client
PACs or names are not certified, and trans-
missions are in the clear. Note that
although uncertified PACs should not be
trusted, they may be useful for debugging,
tracing, and measurement purposes.
+ rpc_c_protect_level_connect - Authenticates
only when the client establishes a rela-
tionship with the server.
+ rpc_c_protect_level_call - Authenticates
only at the beginning of each remote
procedure call when the server receives
the request. This level does not apply
to remote procedure calls made over a
connection-based protocol sequence (that
is, ncacn_ip_tcp). If this level is
specified and the binding handle uses a
connection-based protocol sequence, the
routine uses the rpc_c_protect_level_pkt
level instead.
+ rpc_c_protect_level_pkt - Ensures that
all data received is from the expected
client.
+ rpc_c_protect_level_pkt_integ - Ensures
and verifies that none of the data trans-
ferred between client and server has been
modified. This is the highest protection
level that is guaranteed to be present in
the RPC runtime.
+ rpc_c_protect_level_pkt_privacy -
Authenticates as specified by all of the
previous levels and also encrypts each
RPC argument value. This is the highest
protection level, but is not guaranteed
to be present in the RPC runtime.
authn_svc Specifies the authentication service to use.
The exact level of protection provided by the
authentication service is specified by
protect_level. The supported authentication
services are as follows:
+ rpc_c_authn_none - No authentication:
no tickets are exchanged, no session keys
established, client PACs or names are not
transmitted, and transmissions are in the
clear. Specify rpc_c_authn_none to turn
authentication off for remote procedure
calls made using this binding.
+ rpc_c_authn_dce_secret - DCE shared-secret
key authentication.
+ rpc_c_authn_default - Default authentica-
tion service. The current default authen-
tication service is DCE shared-secret key;
therefore, specifying rpc_c_authn_default
is equivalent to specifying
rpc_c_authn_dce_secret .
+ rpc_c_authn_dce_public - DCE public key
authentication (reserved for future use).
authz_svc Specifies the authorization service implemented
by the server for the interface. The validity
and trustworthiness of authorization data, like
any application data, is dependent on the
authentication service and protection level
specified. The supported authorization services
are as follows:
+ rpc_c_authz_none - Server performs no
authorization. This is valid only if
authn_svc is set to rpc_c_authn_none,
specifying that no authentication is
being performed.
+ rpc_c_authz_name - Server performs
authorization based on the client
principal name. This value cannot be
used if authn_svc is rpc_c_authn_none.
+ rpc_c_authz_dce - Server performs
authorization using the client's DCE
Privilege Attribute Certificate (PAC)
sent to the server with each remote
procedure call made with this binding.
Generally, access is checked against DCE
Access Control Lists (ACLs).
identity A value of type sec_login_handle_t that
represents a complete login context.
sec_timeval_sec_t
A 32-bit integer containing the seconds portion of a UNIX timeval_t,
to be used when expressing absolute dates.
sec_timeval_t
A structure containing the full UNIX time. The structure contains
two 32-bit integers that indicate seconds (sec) and microseconds
(usec) since 0:00, January 1, 1970.
sec_timeval_period_t
A 32-bit integer expressing seconds relative to some well-known
time.
sec_rgy_acct_key_t
Specifies how many parts (person, group, organization) of an account
login name will be enough to specify a unique abbreviation for that
account.
sec_rgy_cursor_t
A structure providing a pointer into a registry database. This type
is used for iterative operations on the registry information. For
example, a call to sec_rgy_pgo_get_members() might return the 10
account names following the input sec_rgy_cursor_t position. Upon
return, the cursor position will have been updated, so the next call
to that routine will return the next 10 names. The components of
this structure are not used by application programs.
sec_rgy_pname_t
A character string of length sec_rgy_pname_t_size.
sec_rgy_name_t
A character string of length sec_rgy_name_t_size.
sec_rgy_login_name_t
A structure representing an account login name. It contains three
strings of type sec_rgy_name_t:
pname The person name for the account.
gname The group name for the account.
oname The organization name for the account.
sec_rgy_member_t
A character string of length sec_rgy_name_t_size. LI
"sec_rgy_foreign_id_t" The representation of a foreign ID. This
structure contains two components:
cell A string of type uuid_t representing the UUID of the
foreign cell.
principal A string of type uuid_t representing the UUID of the
principal.
sec_rgy_sid_t
A structure identifying an account. It contains three fields:
person The UUID of the person part of the account.
group The UUID of the group part of the account.
org The UUID of the organization part of the account.
sec_rgy_unix_sid_t
A structure identifying an account with UNIX ID numbers. It
contains three fields:
person The UNIX ID of the person part of the account.
group The UNIX ID of the group part of the account.
org The UNIX ID of the organization part of the account.
sec_rgy_domain_t
This 32-bit integer specifies which naming domain a character string
refers to: person, group, or organization.
sec_rgy_pgo_flags_t
A 32-bit bitset containing flags pertaining to registry entries.
This type contains the following three flags:
sec_rgy_pgo_is_an_alias
If set, indicates the registry entry is an alias of
another entry.
sec_rgy_pgo_is_required
If set, the registry item is required and cannot be
deleted. An example of a required account is the one
for the registry server itself.
sec_rgy_pgo_projlist_ok
If the accompanying item is a person entry, this flag
indicates the person may have concurrent group sets.
If the item is a group entry, the flag means this group
can appear in a concurrent group set. The flag is
undefined for organization items.
sec_rgy_pgo_item_t
The structure identifying a registry item. It contains five com-
ponents:
id The UUID of the registry item, in uuid_t form.
unix_num A 32-bit integer containing the UNIX ID number of the
registry item.
quota A 32-bit integer representing the maximum number of user-
defined groups the account owner can create.
flags A sec_rgy_pgo_flags_t bitset containing information about
the entry.
fullname A sec_rgy_pname_t character string containing a full name
for the registry entry. For a person entry, this field
might contain the real name of the account owner. For a
group, it might contain a description of the group. This
is just a data field, and registry queries cannot search
on the fullname entry.
sec_rgy_acct_admin_flags_t
A 32-bit bitset containing administration flags used as part of the
administrator's information for any registry account. The set
contains three flags:
sec_rgy_acct_admin_valid
Specifies that the account is valid for login.
sec_rgy_acct_admin_server
If set, the account's name can be used as a server name in
a ticket-granting ticket.
sec_rgy_acct_admin_client
If set, the account's name can be used as a client name in
a ticket-granting ticket.
Note that you can prevent the principal from being authenticated, by
turning off both the sec_rgy_acct_admin_server and the
sec_rgy_acct_admin_client flags.
sec_rgy_acct_auth_flags_t
A 32-bit bitset containing account authorization flags used to
implement authentication policy as defined by the Kerberos Version
5 protocol. The set contains six flags:
sec_rgy_acct_auth_post_dated
Allows issuance of post-dated certificates.
sec_rgy_acct_auth_forwardable
Allows issuance of forwardable certificates.
sec_rgy_acct_auth_tgt
Allows issuance of certificates based on Ticket-Granting
Ticket (TGT) authentication. If this flag is not set, a
client requesting a service may have to supply a password
directly to the server.
sec_rgy_acct_auth_renewable
Allows issuance of renewable certificates.
sec_rgy_acct_auth_proxiable
Allows issuance of proxiable certificates.
sec_rgy_acct_auth_dup_session_key
Allows issuance of duplicate session keys.
sec_rgy_acct_admin_t
The portion of a registry account item containing components
relevant to administrators. This structure consists of the fields
listed below. Note that only expiration_date, good_since_date,
flags, and authentication_flags can be modified by an administrator;
the remaining fields are set by the Security server.
creator This field, in foreign_id_t format, identifies the
administrator who created the registry account.
creation_date
Specifies the creation date of the account, in
sec_timeval_sec_t format.
last_changer
Identifies the last person to change any of the account
information, in foreign_id_t format.
change_date
Specifies the date of the last modification of the account
information, in sec_timeval_sec_t format.
expiration_date
The date after which the account will no longer be valid.
In sec_timeval_sec_t format.
good_since_date
The Kerberos Version 5 TGT revocation date. TGTs issued
before this date will not be honored. In
sec_timeval_sec_t format.
flags Administrative flags in sec_rgy_acct_admin_flags_t format.
authentication_flags
Authentication flags in sec_rgy_acct_auth_flags_t format.
sec_rgy_acct_user_flags_t
A 32-bit bitset containing flags controlling user-modifiable
information. There is only one flag currently implemented. If
sec_rgy_acct_user_passwd_valid is set, it indicates the user pass-
word is valid. If it is not set, this flag prompts the user to
change the password on the next login attempt.
sec_rgy_acct_user_t
A structure containing registry account information. The structure
consists of the fields listed below. Note that only the gecos,
homedir, shell, and flags fields can be modified by the account
owner or other authorized useer; the remaining fields are set by
the Security server.
gecos This is a character string (in sec_rgy_pname_t format)
containing information about the account user. It
generally consists of everything after the full name in
the UNIX gecos format.
homedir The login directory for the account user, in
sec_rgy_pname_t format.
shell The default shell for the account user, in sec_rgy_pname_t
format.
passwd_version_number
An unsigned 32-bit integer, indicating the password
version number. This value is used as output only.
passwd The UNIX encrypted account password, in
sec_rgy_unix_passwd_buf_t format. This value is used as
output only.
passwd_dtm
The date the password was established, in
sec_timeval_sec_t format.
flags Account user flags, in sec_rgy_acct_user_flags_t format.
sec_rgy_plcy_pwd_flags_t
A 32-bit bitset containing two flags about password policy:
sec_rgy_plcy_pwd_no_spaces
If set, will not allow spaces in a password.
sec_rgy_plcy_pwd_non_alpha
If set, requires at least one nonalphanumeric character in
the password.
sec_rgy_plcy_t
A structure defining aspects of registry account policy. It
contains five components:
passwd_min_len
A 32-bit integer describing the minimum number of
characters in the account password.
passwd_lifetime
The number of seconds after a password's creation until it
expires, in sec_timeval_period_t format.
passwd_exp_date
The expiration date of the account password, in
sec_timeval_sec_t format.
acct_lifespan
The number of seconds after the creation of an account
before it expires, in sec_timeval_period_t format.
passwd_flags
Account password policy flags, in sec_rgy_plcy_pwd_flags_t
format.
sec_rgy_plcy_auth_t
This type describes authentication policy. It is a structure
containing two time periods, in sec_timeval_period_t format.
One, max_ticket_lifetime, specifies the maximum length of the
period during which a Ticket-Granting Ticket (TGT) will be valid.
The other, max_renewable_lifetime, specifies the maximum length of
time for which such a ticket may be renewed. This authentication
policy applies both to the registry as a whole as well as
individual accounts. The effective policy for a given account is
defined to bethe more restrictive of the site and principal authen-
tication policy.
sec_rgy_properties_t
A structure describing some registry properties. It contains the
following:
read_version
A 32-bit integer describing the earliest version of the
secd software that can read this registry.
write_version
A 32-bit integer describing the version of the secd soft-
ware that wrote this registry.
minimum_ticket_lifetime
The minimum lifetime of an authentication certificate, in
sec_timeval_period_t format.
default_certificate_lifetime
The "normal" lifetime of an an authentication certificate
(ticket-granting ticket in Kerberos parlance), in
sec_timeval_period_t format. Processes may request
authentication certificates with longer lifetimes up to,
but not in excess of, the maximum allowable lifetime as
determined by the effective policy for the account.
low_unix_id_person
The lowest UNIX number permissible for a person item in
the registry.
low_unix_id_group
The lowest UNIX number permissible for a group item in
the registry.
low_unix_id_org
The lowest UNIX number permissible for an organization
item in the registry.
max_unix_id
The largest UNIX number permissible for any registry
entry.
flags Property flags, in sec_rgy_properties_flags_t format.
realm The name of the cell, in sec_rgy_name_t form, for which
this registry is the authentication service.
realm_uuid
The UUID of the same cell.
sec_rgy_properties_flags_t
A 32-bit bitset, containing flags concerning registry properties:
sec_rgy_prop_readonly
If set (TRUE), indicates that this registry is a query
site.
sec_rgy_prop_auth_cert_unbound
If set (TRUE), the registry server will accept requests
from any site.
sec_rgy_prop_shadow_passwd
If the shadow password flag is set (TRUE), the registry
server will not include the account password when
responding to a request for the user data from a
specified account. This helps minimize the risk of an
account password being intercepted while traveling over
the network.
sec_rgy_prop_embedded_unix_id
Indicates that all UUIDs in this registry contain a UNIX
number embedded. This implies that the UNIX numbers of
objects in the registry cannot be changed, since UUIDs are
immutable.
sec_rgy_override_t
A 32-bit integer used as a flag for registry override mode.
Currently, its possible values are the constants
sec_rgy_no_override and sec_rgy_override. When this mode is
enabled, override data supplied by the node administrator will
replace some of the data gotten from the registry for a given
person/account under certain conditions. These conditions are
as follows:
1. The registry permits the requested overrides to be set for
this machine.
2. The override data is intended for person/account at hand.
When the mode is "override off," data from the registry is returned
to the end user or the application remains untouched.
sec_rgy_mode_resolve_t
A 32-bit integer used as a flag for resolve mode. Currently, its
possible values are the constants sec_rgy_no_resolve_pname and
sec_rgy_resolve_pname. When the mode is enabled, pathnames
containing leading // (slashes) will be translated into a form
understandable by the local machine's NFS.
sec_rgy_unix_passwd_buf_t
A character array of UNIX password strings.
CONSTANTS
The following constants are used in sec_rgy_ calls:
sec_rgy_default_handle
The value of an unbound registry server handle.
sec_rgy_acct_key_t Constants
The following 32-bit integer constants are used with the
sec_rgy_acct_key_t data type:
sec_rgy_acct_key_none
Invalid key.
sec_rgy_acct_key_person
The person name alone is enough.
sec_rgy_acct_key_group
The person and group names are both necessary for the account
abbreviation.
sec_rgy_acct_key_org
The person, group, and organization names are all necessary.
sec_rgy_acct_key_last
Key values must be less than this constant.
sec_rgy_pname_t_size
The maximum number of characters in a sec_rgy_pname_t.
sec_rgy_name_t_size
The maximum number of characters in a sec_rgy_name_t.
sec_rgy_domain_t Constants
The following 32-bit integer constants are the possible values of
the sec_rgy_domain_t data type:
sec_rgy_domain_person
The name in question refers to a person.
sec_rgy_domain_group
The name in question refers to a group.
sec_rgy_domain_org
The name in question refers to an organization.
sec_rgy_pgo_flags_t
A 32-bit constant equal to a variable of type sec_rgy_pgo_flags_t
with no flags set.
sec_rgy_quota_unlimited
A 32-bit integer. Set the quota field of the sec_rgy_pgo_item_t
type to this constant to override the registry quota limitation.
sec_rgy_acct_admin_flags_t
A 32-bit integer. This is the value of the
sec_rgy_acct_admin_flags_t bitset when none of its flags are set.
sec_rgy_acct_auth_flags_none
A 32-bit integer. This is the value of the
sec_rgy_acct_auth_flags_t bitset when none of its flags are set.
sec_rgy_acct_user_flags_t
A 16-bit integer. This is the value of the
sec_rgy_acct_user_flags_t bitset when none of its flags are set.
sec_rgy_plcy_pwd_flags_t
A 16-bit integer. This is the value of the
sec_rgy_policy_pwd_flags_t bitset when none of its flags are set.
sec_rgy_properties_flags_t
A 16-bit integer. This is the value of the
sec_rgy_properties_flags_t bitset when none of its flags are set.
sec_rgy_override
A 32-bit integer, which turns registry override mode on. When this
mode is enabled, override data supplied by the node administrator
will replace some of the data gotten from the registry for a given
person/account under certain conditions.
sec_rgy_no_override
A 32-bit integer, which turns off registry override mode.
sec_rgy_resolve_pname
A 32-bit integer, which turns on registry resolve mode. When the
mode is enabled, pathnames containing leading // (slashes) will be
translated into a form understandable by the local machine's NFS.
sec_rgy_no_resolve_pname
A 32-bit integer, which turns off registry resolve mode.
FILES
SYS$COMMON:[DCE$LIBRARY]RGYBASE.IDL
The idl file from which rgybase.h was derived.
3.2 – EXTENDED_REGISTRY_ATTRIBUTE_DATA_TYPES
SYNOPSIS
#include <dce/sec_attr_base.h>
DATA TYPES
The following data types are used in sec_rgy_attr calls:
sec_attr_twr_ref_t
A pointer to a tower. This data type is used with the
sec_attr_twr_set_t data type to allow a client to pass an
unallocated array of towers, which the server must allocate.
Both data types are used in conjunction with the
sec_attr_bind_type_t data type.
sec_attr_twr_set_t
A structure that defines an array of towers. This data type is used
with the sec_attr_twr_ref_t data type to allow a client to pass an
unallocated array of towers, which the server must allocate. Both
data types are used in conjunction with the sec_attr_bind_type_t
data type. The sec_attr_twr_set_t structure consists of the
following elements:
count An unsigned 32-bit integer specifying the number of towers
in the array.
towers[] An array of pointers (of type sec_attr_twr_ref_t) to
towers.
sec_attr_bind_type_t
A 32-bit integer that specifies the type of binding used by an
attribute interface. The data type (which is used in conjunction
with the sec_attr_binding_t data type) uses the following constants:
sec_attr_bind_type_string
An RPC string binding.
sec_attr_bind_type_twrs
A DCE protocol tower representation of a bindings.
sec_attr_bind_type_svrname
A name in rpc_c_ns_syntax format that identifies a CDS
entry containing the server's binding information. This
constant has the following structure:
name_syntax
Must be rpc_c_ns_syntax_dce to specify that DCE
naming rules are used to specify name.
name A pointer to a name of a CDS entry in
rpc_c_ns_syntax_dce syntax.
sec_attr_binding_t
A discriminated union that supplies information to generate a
binding handle for a attribute trigger. This data type, which is
used in conjunction with the sec_attr_bind_info_t data type, is
composed of the following elements:
bind_type A value of type sec_attr_bind_type_t that defines the type
of binding used by an attribute interface. The contents of
tagged union (below) depend on the value of
sec_attr_bind_type_t.
tagged_union
A tagged union specifying the binding handle. The
contents of the tagged union depend on the value of
bind_type as follows:
If bind_type is... Then tagged_union is...
_______________________________________________________________________
sec_attr_bind_type_string A pointer to an unsigned 32-bit character
string specifying an attribute's RPC string
binding.
_______________________________________________________________________
sec_attr_bind type_twrs An attribute's tower binding representation
of type sec_attr_twr_set_t.
_______________________________________________________________________
sec_attr_bind_svrname A pointer to a name of type
sec_attr_bind_type_t that specifies a
Cell Directory Service entry containing
an attribute trigger's binding information.
sec_attr_binding_p_t
A pointer to a sec_attr_binding_t union.
sec_attr_bind_auth_info_type_t
An enumeration that defines whether or not the binding is authenti-
cated. This data type is used in conjunction with the
sec_attr_bind_auth_info_t data type to set up the authorization
method and parameters for an RPC binding. The
sec_attr_bind_auth_info_type_t type consists of the following
elements:
+ sec_attr_bind_auth_none-The binding is not authenticated.
+ sec_attr_bind_auth_dce-The binding uses DCE shared-secret
key authentication.
sec_attr_bind_auth_info_t
A discriminated union that defines authorization and authentication
parameters for a binding. This data type is used in conjunction with
the sec_attr_bind_auth_info_type_t data type to set up the
authorization method and parameters for an RPC binding. The
sec_attr_bind_auth_info_t data type consists of the following
elements:
info_type A sec_attr_bind_auth_info_type_t data type that specifies
whether or not the binding is authenticated. The contents
of tagged union (below) depend on the value of
sec_attr_bind_auth_info_type_t.
tagged_union
A tagged union specifying the method of authorization and
the authorization parameters. For unauthenticated bindings
(sec_attr_bind_auth_info_type_t = sec_attr_bind_auth_none)
no parameters are supplied. For authenticated bindings
(sec_attr_bind_auth_info_type_t = sec_attr_bind_auth_dce),
the following union is supplied:
svr_princ_name
A pointer to a character string that specifies
the principal name of the server referenced by
the binding handle.
protect_level
An unsigned 32 bit integer indicating the
protection level for RPC calls made using the
server binding handle. The protection level
determines the degree to which authenticated
communications between the client and the
server are protected by the authentication
service specified by authn_svc.
If the RPC runtime or the RPC protocol in the
bound protocol sequence does not support a
specified level, the level is automatically
upgraded to the next higher supported level.
The possible protection levels are as follows:
+ rpc_c_protect_level_default - Uses the
default protection level for the specified
authentication service. The default
protection level for DCE shared-secret
key authentication is
rpc_c_protect_level_pkt_value
+ rpc_c_protect_level_none - Performs no
authentication: tickets are not exchanged,
session keys are not established, client
PACs or names are not certified, and
transmissions are in the clear. Note that
although uncertified PACs should not be
trusted, they may be useful for debugging,
tracing, and measurement purposes.
+ rpc_c_protect_level_connect - Authenticates
only when the client establishes a
relationship with the server.
+ rpc_c_protect_level_call - Authenticates
only at the beginning of each remote
procedure call when the server receives
the request. This level does not apply
to remote procedure calls made over a
connection-based protocol sequence (that
is, ncacn_ip_tcp). If this level is
specified and the binding handle uses a
connection-based protocol sequence, the
routine uses the rpc_c_protect_level_pkt
level instead.
+ rpc_c_protect_level_pkt - Ensures that all
data received is from the expected client.
+ rpc_c_protect_level_pkt_integ - Ensures
and verifies that none of the data trans-
ferred between client and server has been
modified. This is the highest protection
level that is guaranteed to be present in
the RPC runtime.
+ rpc_c_protect_level_pkt_privacy -
Authenticates as specified by all of the
previous levels and also encrypts each
RPC argument value. This is the highest
protection level, but is not guaranteed
to be present in the RPC runtime.
authn_svc Specifies the authentication service to use.
The exact level of protection provided by the
authentication service is specified by
protect_level. The supported authentication
services are as follows:
+ rpc_c_authn_none - No authentication:
no tickets are exchanged, no session keys
established, client PACs or names are not
transmitted, and transmissions are in the
clear. Specify rpc_c_authn_none to turn
authentication off for remote procedure
calls made using this binding.
+ rpc_c_authn_dce_secret - DCE shared-secret
key authentication.
+ rpc_c_authn_default - Default authentica-
tion service. The current default authen-
tication service is DCE shared-secret key;
therefore, specifying rpc_c_authn_default
is equivalent to specifying
rpc_c_authn_dce_secret.
+ rpc_c_authn_dce_public - DCE public key
authentication (reserved for future use).
authz_svc Specifies the authorization service implemented
by the server for the interface. The validity
and trustworthiness of authorization data, like
any application data, is dependent on the
authentication service and protection level
specified. The supported authorization services
are as follows:
+ rpc_c_authz_none - Server performs no
authorization. This is valid only if
authn_svc is set to rpc_c_authn_none,
specifying that no authentication is
being performed.
+ rpc_c_authz_name - Server performs
authorization based on the client
principal name. This value cannot be
used if authn_svc is rpc_c_authn_none.
+ rpc_c_authz_dce - Server performs
authorization using the client's DCE
Privilege Attribute Certificate (PAC)
sent to the server with each remote
procedure call made with this binding.
Generally, access is checked against DCE
Access Control Lists (ACLs).
sec_attr_bind_info_t
A structure that specifies attribute trigger binding information.
This data type, which is used in conjunction with the
sec_attr_schema_entry_t data type, contains of the following
elements:
auth_info The binding authorization information of type
sec_attr_bind_auth_info_t.
num_bindings
An unsigned 32-bit integer specifying the number of
binding handles in bindings.
bindings An array of sec_attr_binding_t data types that specify
binding handles.
sec_attr_bind_info_p_t
A pointer to a sec_attr_bind_info_t union.
sec_attr_encoding_t
An enumerator that contains attribute encoding tags used to define
the legal encodings for attribute values. The data type, which is
used in conjunction with the sec_attr_value_t and
sec_attr_schema_entry_t data types, consists of the following
elements:
sec_attr_enc_any
The attribute value can be of any legal encoding type.
This encoding tag is legal only in a schema entry. An
attribute entry must contain a concrete encoding type.
sec_attr_enc_void
The attribute has no value. It is simple a marker that is
either present or absent.
sec_attr_enc_printstring
The attribute value is a printable IDL string in DCE
Portable Character Set.
sec_attr_enc_printstring_array
The attribute value is an array of printstrings.
sec_attr_enc_integer
The attribute value is a signed 32-bit integer.
sec_attr_enc_bytes
The attribute value is a string of bytes. The string is
assumed to be a pickle or some other self describing type.
(See also the sec_attr_enc_bytes_t data type.)
sec_attr_enc_confidential_bytes
The attribute value is a string of bytes that have been
encrypted in the key of the principal object to which the
attribute is attached. The string is assumed to be a
pickle or some other self describing type. This encoding
type is useful only when attached to a principal object,
where it is decrypted and encrypted each time the
principal's password changes. (See also the
sec_attr_enc_bytes_t data type.)
sec_attr_enc_i18n_data
The attribute value is an "internationalized" string of
bytes with a tag identifying the OSF registered codeset
used to encode the data. (See also the
sec_attr_i18n_data_t data type.)
sec_attr_enc_uuid
The attribute is a value of type uuid_t, a DCE UUID.
sec_attr_enc_attr_set
The attribute value is an attribute set, a vector of
attribute UUIDs used to associate multiple related
attribute instances which are members of the set.
(See also the sec_attr_enc_attr_set_t data type.)
sec_attr_enc_binding
The attribute value is a sec_attr_bind_info_t data type
that specifies DCE server binding information.
sec_attr_enc_trig_binding
This encoding type is returned by rs_attr_lookup call. It
informs the client agent of the trigger binding informa-
tion of an attribute with a query trigger.
Unless sec_attr_enc_void or sec_attr_enc_any is specified, the attribute
values must conform to the attribute's encoding type.
sec_attr_enc_bytes_t
A structure that defines the length of attribute encoding values for
attributes encoded as sec_attr_enc_bytes and
sec_attr_enc_confidential_bytes. The structure, which is used in
conjunction with the sec_attr_value_t data type, consists of:
An unsigned 32-bit integer that defines the data length.
data[] An array of bytes specifying the length of attribute
encoding data.
sec_attr_i18n_data_t
A structure that defines the codeset used for attributes encoded as
sec_attr_enc_il8n_data and the length of the attribute encoding
values. The structure, which is used in conjunction with the
sec_attr_value_t data type, consists of:
An unsigned 32-bit identifier of a codeset registered with
the Open Software Foundation.
An unsigned 32-bit integer that defines the data length.
data[] An array of bytes specifying the length of attribute
encoding data.
sec_attr_enc_attr_set_t
A structure that that supplies the UUIDs of each member of an
attribute set. The structure, which is used in conjunction with
the sec_attr_value_t data type, consists of:
num_members
An unsigned 32-bit integer specifying the total number of
attribute's in the set.
members[] An array containing values of type uuid_t, the UUID of
each member in the set.
sec_attr_enc_printstring_t
A structure that contains a printstring.
sec_attr_enc_printstring_p_t
A pointer to a sec_attr_enc_printstring_t structure.
sec_attr_enc_str_array_t
A structure that defines a printstring array. It consists of:
num_strings
An unsigned 32-bit integer specifying the number of
strings in the array.
strings[] An array of pointers (of type
sec_attr_enc_print_string_p_t) to printstrings.
sec_attr_value_t
A discriminated union that defines attribute values. The union,
which is used in conjunction with the sec_attr_t data type,
consists of the following elements:
attr_encoding
A sec_attr_encoding_t data type that defines attribute
encoding. The contents of tagged union (below) depend
on the value of sec_attr_encoding_t.
tagged_union
A tagged union whose contents depend on attr_encoding as
follows:
If attr_encoding is... Then tagged_union is...
_______________________________________________________________________
sec_attr_enc_void NULL
_______________________________________________________________________
sec_attr_enc_printstring A pointer to printstring
_______________________________________________________________________
sec_attr_enc_printstring_array A pointer to an array of
printstrings
_______________________________________________________________________
sec_attr_enc_integer signed_int, a 32-bit signed integer
_______________________________________________________________________
sec_attr_enc_bytes bytes, a pointer to a structure of
type sec_attr_enc_bytes_t
_______________________________________________________________________
sec_attr_enc_confidential_bytes bytes, a pointer to a structure of
type sec_attr_enc_bytes_t
_______________________________________________________________________
sec_attr_enc_i18n_data idata, a pointer to a structure of
type sec_attr_i18n_data_t
_______________________________________________________________________
sec_attr_end_uuid uuid, a value of type uuid_t
_______________________________________________________________________
sec_attr_enc_attr_set attr_set, a pointer to a structure of
type sec_attr_enc_attr_set_t
_______________________________________________________________________
sec_attr_enc_binding binding, a pointer to a structure of
type sec_attr_binding_info_t
sec_attr_t
A structure that defines an attribute. The structure consists of:
attr_id A value of type uuid_t, the UUID of the attribute.
attr_value
A value of type sec_attr_value_t.
sec_attr_acl_mgr_info_t
A structure that contains the access control information defined in
a schema entry for an attribute. The structure, which is used in
conjunction with the sec_attr_schema_entry_t data type, consists of
the following elements:
acl_mgr_type
The value of type uuid_t that specifies the UUID of the
ACL manager type that supports the object type to which
the attribute can be attached. This field provides a
well-defined context for evaluating the permission bits
needed to operate on the attribute. The following table
lists the ACL Manager types for registry objects.
Registry Object ACL Manager Type Valid
Type Permissions
____________________________________________________________________
principal 06ab9320-0191-11ca-a9e8-08001e039d7d rcDnfmaug
____________________________________________________________________
group 06ab9640-0191-11ca-a9e8-08001e039d7d rctDnfmM
____________________________________________________________________
organization 06ab9960-0191-11ca-a9e8-08001e039d7d rctDnfmM
____________________________________________________________________
directory 06ab9c80-0191-11ca-a9e8-08001e039d7d rcidDn
____________________________________________________________________
policy 06ab8f10-0191-11ca-a9e8-08001e039d7d rcma
____________________________________________________________________
replist 2ac24970-60c3-11cb-b261-08001e039d7d cidmAI
query_permset
Data of type sec_acl_permset_t that defines the permission
bits needed to access the attribute's value.
update_permset
Data of type sec_acl_permset_t that defines the permission
bits needed to update the attribute's value.
test_permset
Data of type sec_acl_permset_t that defines the permission
bits needed to test the attribute's value.
delete_permset
Data of type sec_acl_permset_t that defines the permission
bits needed to delete an attribute instance.
sec_attr_acl_mgr_info_p_t
A pointer to a sec_attr_acl_mgr_info_t structure.
sec_attr_acl_mgr_info_set_t
A structure that defines an attribute's ACL manager set. The
structure consists of the following elements:
num_acl_mgrs
An unsigned 32-bit integer that specifies the number of
ACL managers in the ACL manager set.
mgr_info[]
An array of pointers of type sec_attr_mgr_info_p_t that
define the ACL manager types in the ACL manager set and
the permission sets associated with the ACL manager type.
sec_attr_intercell_action_t
An enumerator that specifies the action that should be taken by the
Privilege Service when it reads acceptable attributes from a foreign
cell. A foreign attribute is acceptable only if there is either a
schema entry for the foreign cell or if
sec_attr_intercell_act_accept is set to true.
This enumerator, which is used in conjunction with the
sec_attr_schema_entry_t data type, is composed of the following ele-
ments:
sec_attr_intercell_act_accept
If the unique flag in the sec_attr_schema_entry_t data
type is not set on, retain the attribute. If the unique
flag is set on, retain the attribute only if its value
is unique among all attribute instances of the same
attribute type within the cell.
sec_attr_intercell_act_reject
Discard the input attribute.
sec_attr_intercell_act_evaluate
Use the binding information in the trig_binding field of
this sec_attr_schema_entry_t data type to make a
sec_attr_trig_query call to a trigger server. That server
determines whether to retain the attribute value, discard
the attribute value, or map the attribute to another
value(s).
sec_attr_trig_type_t
Specifies the trigger type, a flag that determines whether an
attribute trigger should be invoked for query operations. The
data type, which is used in conjunction with the
sec_attr_schema_entry_t data type, uses the following constants:
The attribute trigger server is invoked for query opera-
tions.
sec_attr_trig_type_query
The attribute trigger server is invoked for update opera-
tions.
sec_attr_schema_entry_t
A structure that defines a complete attribute entry for the schema
catalog. The entry is identified by both a unique string name and a
unique attribute UUID. Although either can either can be used as a
retrieval key, the string name should be used for interactive access
to the attribute and the UUID for programmatic access. The attribute
UUID is used to identify the semantics defined for the attribute
type in the schema.
The sec_attr_schema_entry_t data type consists of the following ele-
ments:
attr_name A pointer to the attribute name.
attr_id A value of type uuid_t that identifies the attribute type.
attr_encoding
An enumerator of type sec_attr_encoding_t that specifies
the attribute's encoding.
acl_mgr_set
A structure of type sec_attr_acl_mgr_info_set_t that
specifies the ACL manager types that support the objects
on which attributes of this type can be created and the
permission bits supported by that ACL manager type.
schema_entry_flags
An unsigned integer of type sec_attr_sch_entry_flags_t
that defines bitsets for the following flags:
unique When set on, this flag indicates that each
instance of this attribute type must have a
unique value within the cell for the object
type implied by the ACL Manager type. If this
flag is not set on, uniqueness checks are not
performed for attribute writes.
multi_valued
When set on, this flag indicates that this
attribute type may be multi-valued; in other
words, multiple instances of the same
attribute type can be attached to a single
registry object. If this flag is not set on,
only one instance of this attribute type can
be attached to an object.
reserved When set on, this flag prevents the schema entry
from being deleted through any interface or by
any user. If this flag is not set on, the
entry can be deleted by any authorized
principal.
use_defaults
When set on, the system-defined default
attribute value will be returned on a client
query if an instance of this attribute does
not exist on the queried object. If this
flag is not set on, system defaults are not
used.
intercell_action
An enumerator of type sec_attr_intercell_action_t that
specifies how the Privilege Service will handle
attributes from a foreign cell.
trig_types
A flag of type sec_attr_trig_type_t that specifies whether
whether a trigger can perform update or query operations.
trig_binding
A pointer to a structure of type sec_attr_bind_info_t that
supplies the attribute trigger binding handle.
scope A pointer to a string that defines the objects to which
the attribute can be attached.
comment A pointer to a string that contains general comments about
the attribute.
sec_attr_schema_entry_parts_t
A 32-bit bitset containing flags that specify the schema entry
fields that can be modified on a schema entry update operation.
This data type contains the following flags:
sec_attr_schema_part_name
If set, indicates that the attribute name (attr_name) can
be changed.
sec_attr_schema_part_reserved
If set, indicates that the setting of the flag that deter-
mines whether or not the schema entry can be deleted
(reserved) can be changed.
sec_attr_schema_part_defaults
If set, indicates that the flag that determines whether or
not a query for a non-existent attribute will not result
in a search for a system default (apply_default) can be
changed.
sec_attr_schema_part_trig_bind
If set, indicates that the trigger's binding information
(trig_binding) can be changed.
sec_attr_schema_part_comment
If set, indicates whether or not comments associated with
the schema entry (comment) can be changed.
sec_attr_component_name_t
A pointer to a character string used to further specify the object
to which the attribute is attached. (Note that this data type is
analogous to the sec_acl_component_name_t data type in the ACL
interface.)
sec_attr_cursor_t
A structure that provides a pointer into a registry database and is
used for multiple database operations.
This cursor must minimally represent the object indicated by
xattrschema in the schema interfaces, or component_name in the
attribute interfaces. The cursor may additionally represent an
entry within that schema or an attribute instance on that component.
sec_attr_srch_cursor_t
A structure that provides a pointer into a registry database and is
used for multiple database operations. The cursor must minimally
represent the list of all objects managed by this server that
possess the search attributes specified in the
sec_attr_srch_cursor_init routine. It may additionally represent
a given object within this list as well as attribute instance(s)
possessed by that object.
sec_attr_trig_cursor_t
A structure that provides an attribute trigger cursor for inter-
active operations. The structure consists of the following
elements:
source A value of type uuid_t that provides a UUID to identify
the server that initialized the cursor.
object_handle
A signed 32 bit integer that identifies the object
(specified by xattrschema in the schema interface or
component_name in the attribute interface) upon which
the operation is being performed.
entry_handle
A signed 32 bit integer that identifies the current entry
(schema_entry in the schema interface or attribute
instance in the attribute interface) for the operation.
valid A boolean field with the following values:
+ true (1) - Indicates an initialized cursor.
+ false (0) - Indicates an uninitialized cursor.
sec_attr_trig_timeval_sec_t
A 32-bit integer containing the seconds portion of a UNIX timeval_t,
to be used when expressing absolute dates.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_ATTR_BASE.IDL
The idl file from which sec_attr_base.h was derived.
CONSTANTS
The following constants are used in sec_attr calls:
sec_attr_bind_auth_dce
The binding uses DCE shared-secret key authentication.
sec_attr_bind_auth_none
The binding is not authenticated.
sec_attr_bind_type_string
The attribute uses an rpc string binding.
sec_attr_bind_type_svrname
The attribute uses a name in rpc_c_ns_syntax format that identifies
a CDS entry containing the server's binding information. This
constant has the following structure:
name_syntax
Must be rpc_c_ns_syntax_dce to specify that DCE naming
rules are used to specify name.
name A pointer to a name of a CDS entry in rpc_c_ns_syntax_dce
syntax.
sec_attr_bind_type_twr
The attribute uses a DCE protocol tower binding representation.
sec_attr_trig_type_t Constants
The following 32-bit constants are used with the
sec_attr_trig_type_t data type:
sec_attr_trig_type_query The trigger server can perform only
query operations.
sec_attr_trig_type_update The trigger server can perform only
update operations.
sec_attr_intercell_action_t Constants
The following constants are used with the
sec_attr_intercell_action_t data type
sec_attr_intercell_act_accept
If the unique flag in the sec_attr_schema_entry_t data type is
not set on, retain attributes from a foreign cell. If the unique
flag is set on, retain the foreign attribute only if its value
is unique among all attribute instances of the same attribute
type within the cell.
sec_attr_intercell_act_reject
Discard attributes from a foreign cell.
sec_attr_intercell_act_evaluate
A trigger server determines whether to retain foreign
attributes, discard foreign attributes, or map foreign
attribute to another value(s).
sec_attr_schema_entry_parts_t Constants
The following constants are used with the
sec_attr_schema_entry_parts_t data type:
sec_attr_schema_part_name
Indicates that the attribute name can be changed in an schema
update operation.
sec_attr_schema_part_reserved
Indicates that the setting of the reserved flag can be changed
in a schema entry update.
sec_attr_schema_part_defaults
Indicates that the apply_default flag can be changed in a schema
entry update operation.
sec_attr_schema_part_trig_bind
Indicates that trigger binding information can be changed in a
schema entry update operation.
sec_attr_schema_part_comment
Indicates that comments associated with the schema entry can be
changed in a schema entry update.
3.3 – LOGIN_API_DATA_TYPES
SYNOPSIS
#include <dce/sec_login.h>
DATA TYPES
The following data types are used in sec_login_ calls:
sec_login_handle_t
This is an opaque pointer to a data structure representing a
complete login context. The context includes a principal's network
credentials, as well as other account information. The network
credentials are also referred to as the principal's "ticket-granting
ticket."
sec_login_flags_t
A 32-bit set of flags describing restrictions on the use of a
principal's validated network credentials. Currently, only one flag
is implemented, and the set can take on the following two values:
sec_login_no_flags
No special flags are set.
sec_login_credentials_private
Restricts the validated network credentials to the current
process. If this flag is not set, it is permissible to
share credentials with descendents of current process.
sec_login_auth_src_t
An enumerated set describing how the login context was authorized.
The possible values are:
sec_login_auth_src_network
Authentication accomplished through the normal network
authority. A login context authenticated this way will
have all the network credentials it ought to have.
sec_login_auth_src_local
Authentication accomplished via local data. Authentication
occurs locally if a principal's account is tailored for
the local machine, or if the network authority is
unavailable. Since login contexts authenticated locally
have no network credentials, they may not be used for
network operations.
sec_login_auth_src_overridden
Authentication accomplished via the override facility.
sec_login_passwd_t
The sec_login_get_pwent() call will return a pointer to a "password"
structure, which depends on the underlying registry structure. In
most cases, the structure will look like that supported by Berkeley
4.4BSD and OSF/1, which looks like this:
struct passwd {
char *pw_name; * user name *
char *pw_passwd; * encrypted password *
int pw_uid; * user uid *
int pw_gid; * user gid *
time_t pw_change; * password change time *
char *pw_class; * user access class *
char *pw_gecos; * Honeywell login info *
char *pw_dir; * home directory *
char *pw_shell; * default shell *
time_t pw_expire; * account expiration *
};
sec_passwd_rec_t
A structure containing either a plaintext password or a preencrypted
buffer of password data. The sec_passwd_rec_t structure consists of
three components:
version_number
The version number of the password.
pepper A character string combined with the password before an
encryption key is derived from the password.
key A structure consists of the following components:
key_type
The key type can be the following:
sec_passwd_plain
Indicates that a printable string of data is
stored in plain.
sec_passwd_des
Indicates that an array of data is stored in
des_key.
tagged_union
A structure specifying the password. The value of
the structure depends on key_type. If key_type is
sec_passwd_plain, structure contains plain, a
character string. If key_type is sec_passwd_des,
the structure contains des_key, a DES key of type
sec_passwd_des_key_t.
CONSTANTS
The following constants are used in sec_login_ calls:
sec_login_default_handle
The value of a login context handle before setup or validation.
sec_login_flags_t Constants
The following two constants are used with the sec_login_flags_t
type.
sec_login_no_flags
No special flags are set.
sec_login_credentials_private
Restricts the validated network credentials to the current
process. If this flag is not set, it is permissible to
share credentials with descendents of current process.
sec_login_remote_uid
Used in the sec_login_passwd_t structure for users from remote
cells.
sec_login_remote_gid
Used in the sec_login_passwd_t structure for users from remote
cells.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which sec_login.h was derived.
3.4 – EXTENDED_PRIVILEGE_ATTRIBUTE_API_DATA_TYPES
SYNOPSIS
#include <dce/id_epac.h>
#include <dce/nbase.h>
DATA TYPES
The following data types are used in Extended Privilege Attribute calls
and in the sec_login_cred calls that implement extended privilege
attributes.
sec_cred_cursor_t
A structure that provides an input/output cursor used to iterate
through a set of delegates in the sec_cred_get_delegate() or
sec_login_cred_get_delegate() calls. This cursor is initialized by
the sec_cred_initialize_cursor() or sec_login_cred_init_cursor()
call.
sec_cred_attr_cursor_t
A structure that provides an input/output cursor used to iterate
through a set of extended attributes in the
sec_cred_get_extended_attributes() call. This cursor is initialized
by the sec_cred_initialize_attr_cursor() call.
sec_id_opt_req_t
A structure that specifies application-defined optional
restrictions. The sec_id_opt_req_t data type is composed of the
following elements:
restriction_len
An unsigned 16-bit integer that defines the size of the
restriction data.
restrictions
A pointer to a byte_t that contains the restriction data.
sec_rstr_entry_type_t
An enumerator that specifies the entry types for delegate and target
restrictions. This data type is used in conjunction with the
sec_id_restriction_t data type where the specific UUID(s), if
appropriate, are supplied. It consists of the following components:
sec_rstr_e_type_user
The target is a local principal identified by UUID. This
type conforms with the POSIX 1003.6 standard.
sec_rstr_e_type_group
The target is a local group identified by UUID. This type
conforms with the POSIX 1003.6 standard.
sec_rstr_e_type_foreign_user
The target is a foreign principal identified by principal
and cell UUID.
sec_rstr_e_type_foreign_group
The target is a foreign group identified by group and cell
UUID.
sec_rstr_e_type_foreign_other
The target is any principal that can authenticate to the
foreign cell identified by UUID.
sec_rstr_e_type_any_other
The target is any principal that can authenticate to any
cell, but is not identified in any other type entry.
sec_rstr_e_type_no_other
No pincipal can act as a target or delegate.
sec_id_restriction_t
A discriminated union that defines delegate and target restrictions.
The union, which is used in conjunction with the
sec_restriction_set_t data type, consists of the following elements:
entry_type
A sec_rstr_entry_type_t that defines the ACL entry types
for delegate and target restrictions. The value of
tagged_union depends on the value of entry_type.
tagged_union
A tagged union whose contents depend on entry_type as fol-
lows:
If entry_type is... Then tagged_union is...
________________________________________________________________
sec_rstr_e_type_any_other NULL
________________________________________________________________
sec_rstr_e_type_foreign_other foreign_id that identifies
the foreign cell.
________________________________________________________________
sec_rstr_e_type_user id, a sec_id_t that
sec_rstr_e_type_group identifies the user or group.
________________________________________________________________
sec_rstr_e_type_foreign_user foreign_id, a sec_id_foreign_t
sec_rstr_e_type_foreign_group that identifies the foreign user
or group.
sec_id_restriction_set_t
A structure that that supplies delegate and target restrictions. The
structure consists of:
num_restrictions
A 16-bit unsigned integer that defines the number of
restrictions in restrictions.
restrictions
A pointer to a sec_id_restriction_t that contains the res-
trictions.
sec_id_compatibility_mode_t
A unsigned 16 bit integer that defines the compatibility between
current and pre-1.1 servers. The data type uses the following con-
stants:
sec_id_compat_mode_none
Compatibility mode is off.
sec_id_compat_mode_initiator
Compatibility mode is on. The 1.0 PAC data extracted from
the EPAC of the chain initiator.
sec_id_compat_mode_caller
Compatibility mode is on. The 1.0 PAC data extracted from
the last delegate in the delegation chain.
sec_id_delegation_type_t
An unsigned 16 bit integer that defines the delegation type. The
data type uses the following constants:
sec_id_deleg_type_none
Delegation is not allowed.
sec_id_deleg_type_traced
Traced delegation is allowed.
sec_id_deleg_type_impersonation
Simple (impersonation) delegation is allowed.
sec_id_pa_t
An structure that contains pre-1.1 PAC data extracted from an EPAC
of a current version server. This data type, which is used for
compatibility with pre-1.1 servers, consists of the following
elements:
realm A value of type sec_id_t that contains the UUID that
identifies the cell in which the principal associated
with the PAC exists.
principal A value of type sec_id_t that contains the UUID of the
principal.
group A value of type sec_id_t that contains the UUID of the
principal's primary group.
num_groups
An unsigned 16-bit integer that specifies the number of
groups in the principal's groupset.
groups An array of pointers to sec_id_ts that contain the UUIDs
of the each group in the principal's groupset.
num_foreign_groupsets
An unsigned 16-bit integer that specifies the number of
foreign groups for the principal's groupset.
foreign_groupsets
An array of pointers to sec_id_ts that contain the UUIDs
of the each group in the principal's groupset.
sec_id_pac_t
An structure that contains a pre-1.1 PAC. This data type, which is
used as output of the sec_cred_get_v1_pac call, consists of the
following elements:
pac_type A value of type sec_id_pac_format_t that can be used to
describe the PAC format.
authenticated
A boolean field that indicates whether or not the PAC is
authenticated (obtained from an authenticated source).
FALSE indicates that the PAC is not authenticated. No
authentication protocol was used in the rpc that trans-
mitted the identity of the caller. TRUE indicates that
the PAC is authenticated.
realm A value of type sec_id_t that contains the UUID that
identifies the cell in which the principal associated
with the PAC exists.
principal A value of type sec_id_t that contains the UUID of the
principal.
group For local principals, a value of type sec_id_t that
contains the UUID of the principal's primary group.
num_groups
An unsigned 16-bit integer that specifies the number of
groups in the principal's groupset.
groups An array of pointers to sec_id_ts that contain the UUIDs
of the each group in the principal's groupset.
num_foreign_groups
An unsigned 16-bit integer that specifies the number of
foreign groups in the principal's groupset.
foreign_groups
An array of pointers to sec_id_ts that contain the UUIDs
of the each foreign group in the principal's groupset.
sec_id_pac_format_t
An enumerator that can be used to describe the PAC format.
sec_id_t
A structure that contains UUIDs for principals, groups, or organiza-
tions and an optional printstring name. Since a UUID is an handle
for the object's identity, the sec_id_t data type is the basic unit
for identifying principals, groups, and organizations.
Because the printstring name is dynamically allocated, this datatype
requires a destructor function. Generally, however, the sec_id_t is
embedded in other data types (ACLs, for example), and these data-
types have a destructor function to release the printstring storage.
The sec_id_t data type is composed of the following elements:
uuid A value of type uuid_t, the UUID of the principal, group,
or organization.
name A pointer to a character string containing the name of the
principal, group, or organization.
sec_id_foreign_t
A structure that contains UUIDs for principals, groups, or organiza-
tions for objects in a foreign cell and the UUID that identifies the
foreign cell. The sec_id_foreign_t data type is composed of the
following elements:
id A value of type sec_id_t that contains the UUIDs of the
objects from the foreign cell.
realm A value of type sec_id_t that contains the UUID of the
foreign cell.
sec_id_foreign_groupset_t
A structure that contains UUIDs for set of groups in a foreign
cell and the UUID that identifies the foreign cell. The
sec_id_foreign_groupset_t data type is composed of the following
elements:
realm A value of type sec_id_t that contain the UUID of the
foreign cell.
num_groups
An unsigned 16-bit integer specifying the number of group
UUIDs in groups.
groups A printer to a sec_id_t that contains the UUIDs of the
groupset from the foreign cell.
CONSTANTS
The following constants are used in the Extended Privilege Attribute
calls and in the the sec_login calls that implement extended privilege
attributes:
sec_id_compat_mode_none
Compatibility mode is off.
sec_id_compat_mode_initiator
Compatibility mode is on. The 1.0 PAC data extracted from the EPAC
of the chain initiator.
sec_id_compat_mode_caller
Compatibility mode is on. The 1.0 PAC data extracted from the last
delegate in the delegation chain.
sec_id_deleg_type_none
Delegation is not allowed.
sec_id_deleg_type_traced
Traced delegation is allowed.
sec_id_deleg_type_impersonation
Simple (impersonation) delegation is allowed.
sec_rstr_e_type_user
The delegation target is a local principal identified by UUID. This
type conforms with the POSIX 1003.6 standard.
sec_rstr_e_type_group
The delegation target is a local group identified by UUID. This type
conforms with the POSIX 1003.6 standard.
sec_rstr_e_type_foreign_user
The delegation target is a foreign principal identified by principal
and cell UUID.
sec_rstr_e_type_foreign_group
The delegation target is a foreign group identified by group and
cell UUID.
sec_rstr_e_type_foreign_other
The delegation target is any principal that can authenticate to the
foreign cell identified by UUID.
sec_rstr_e_type_any_other
The delegation target is any principal that can authenticate to any
cell, but is not identified in any other type entry.
sec_rstr_e_type_no_other
No principal can act as a target or delegate.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_CRED.IDL
The idl file from which sec_cred.h was derived.
SYS$COMMON:[DCE$LIBRARY]ID_EPAC.IDL
The idl file from which id_epac.h was derived.
SYS$COMMON:[DCE$LIBRARY]NBASE.IDL
The idl file from which nbase.h was derived.
3.5 – ACL_API_DATA_TYPES
SYNOPSIS
#include <dce/aclbase.h>
Data Types
The following data types are used in sec_acl_ calls:
sec_acl_handle_t
A pointer to an opaque handle bound to an ACL that is the subject
of a test or examination. The handle is bound to the ACL with
sec_acl_bind(). An unbound handle has the value
sec_acl_default_handle.
sec_acl_posix_semantics_t
A flag that indicates which, if any, POSIX ACL semantics an ACL
manager supports. The following constants are defined for use
with the sec_acl_posix_semantics_t data type:
sec_acl_posix_no_semantics
The manager type does not support POSIX semantics.
sec_acl_posix_mask_obj
The manager type supports the mask_obj entry type and
POSIX 1003.6 Draft 12 ACL mask entry semantics.
sec_acl_t
This data type is the fundamental type for the ACL manager
interfaces. The sec_acl_t type contains a complete access control
list, made up of a list of entry fields (type sec_acl_entry_t).
The default cell identifies the authentication authority for
simple ACL entries (foreign entries identify their own foreign
cells). The sec_acl_manager_type identifies the manager to
interpret this ACL. The sec_acl_t type is a structure containing
the following fields:
default_realm
A structure of type sec_acl_id_t, this identifies the UUID
and (optionally) the name of the default cell.
sec_acl_manager_type
Contains the UUID of the ACL manager type.
num_entries
An unsigned 32-bit integer containing the number of ACL
entries in this ACL.
sec_acl_entries
An array containing num_entries pointers to different ACL
entries, each of type sec_acl_entry_t.
sec_acl_p_t
This data type, simply a pointer to a sec_acl_t, is for use with the
sec_acl_list_t data type.
sec_acl_list_t
This data type is a structure containing an unsigned 32-bit integer
num_acls that describes the number of ACLs indicated by its
companion array of pointers, sec_acls, of type sec_acl_p_t.
sec_acl_entry_t
The sec_acl_entry_t type is a structure made up of the following
components:
perms A set of flags of type sec_acl_permset_t that describe the
permissions granted for the principals identified by this
ACL entry. Note that if a principal matches more than one
ACL entry, the effective permissions will be the most
restrictive combination of all the entries.
entry_info
A structure containing two members:
entry_type
A flag of type sec_acl_entry_type_t, indicating
the type of ACL entry.
tagged_union
A tagged union whose contents depend on the type
of the entry.
The types of entries indicated by entry_type can be the following:
sec_acl_e_type_user_obj
The entry contains permissions for the implied user object. This
type is described in the POSIX 1003.6 standard.
sec_acl_e_type_group_obj
The entry contains permissions for the implied group object.
This type is described in the POSIX 1003.6 standard.
sec_acl_e_type_other_obj
The entry contains permissions for principals not otherwise
named through user or group entries. This type is described
in the POSIX 1003.6 standard.
sec_acl_e_type_user
The entry contains a key that identifies a user. This type is
described in the POSIX 1003.6 standard.
sec_acl_e_type_group
The entry contains a key that identifies a group. This type is
described in the POSIX 1003.6 standard.
sec_acl_e_type_mask_obj
The entry contains the maximum permissions for all entries other
than mask_obj, unauthenticated, user_obj, other_obj.
sec_acl_e_type_foreign_user
The entry contains a key that identifies a user and the foreign
realm.
sec_acl_e_type_foreign_group
The entry contains a key that identifies a group and the foreign
realm.
sec_acl_e_type_foreign_other
The entry contains a key that identifies a foreign realm. Any
user that can authenticate to the foreign realm will be allowed
access.
sec_acl_e_type_any_other
The entry contains permissions to be applied to any accessor who
can authenticate to any realm, but is not identified in any
other entry (except sec_acl_e_type_unauthenticated).
sec_acl_e_type_unauthenticated
The entry contains permissions to be applied when the accessor
does not pass authentication procedures. A privilege attribute
certificate will indicate that the caller's identity is not
authenticated. The identity is used to match against the
standard entries, but the access rights are masked by this mask.
If this mask does not exist in an ACL, the ACL is assumed to
grant no access and all unauthenticated access attempts will be
denied.
Great care should be exercised when allowing unauthenticated
access to an object. Almost by definition, unauthenticated
access is very easy to spoof. The presence of this mask on
an ACL essentially means that anyone can get at least as much
access as allowed by the mask.
sec_acl_e_type_extended
The entry contains additional "pickled" data. This kind of
entry cannot be interpreted, but can be used by an out-of-date
client when copying an ACL from one manager to another
(assuming that the two managers each understand the data).
The contents of the tagged union depend on the entry type.
For the following entry types, the union contains a UUID and an optional
print string (called entry_info.tagged_union.id with type sec_id_t) for
an identified local principal, or for an identified foreign realm.
+ sec_acl_e_type_user
+ sec_acl_e_type_group
+ sec_acl_type_foreign_other
For the following entry types, the union contains two UUIDs and optional
print strings (called entry_info.tagged_union.foreign_id with type
sec_id_foreign_t) for an identified foreign principal and its realm.
+ sec_acl_e_type_foreign_user
+ sec_acl_e_type_foreign_group
For an extended entry (sec_acl_e_type_extended), the union contains
entry_info.tagged_union.extended_info, a pointer to an information block
of type sec_acl_extend_info_t.
sec_acl_permset_t
A 32-bit set of permission flags. The flags currently represent the
conventional file system permissions (read, write, execute) and the
extended DFS permissions (owner, insert, delete). The "unused"
flags represent permissions that can only be interpreted by the
manager for the object. For example, sec_acl_perm_unused_00000080
may mean to one ACL manager that withdrawals are allowed, and to
another ACL manager that rebooting is allowed.
The following constants are defined for use with the
sec_acl_permset_t data type:
sec_acl_perm_read
The ACL allows read access to the protected object.
sec_acl_perm_write
The ACL allows write access to the protected object.
sec_acl_perm_execute
The ACL allows execute access to the protected object.
sec_acl_perm_control
The ACL allows the ACL itself to be modified.
sec_acl_perm_insert
The ACL allows insert access to the protected object.
sec_acl_perm_delete
The ACL allows delete access to the protected object.
sec_acl_perm_test
The ACL allows access to the protected object only to the
extent of being able to test for existence.
The bits from 0x00000080 to 0x80000000 are not used by the
conventional ACL permission set. Constants of the form
sec_acl_perm_unused_00000080 have been defined so application
programs can easily use these bits for extended ACLs.
sec_acl_extend_info_t
This is an extended information block, provided for future
extensibility. Primarily, this allows an out-of-date client to
read an ACL from a newer manager and apply it to another (up-to-
date) manager. The data cannot be interpreted by the out-of-date
client without access to the appropriate "pickling" routines
(that presumably are unavailable to such a client).
In general, ACL managers should not accept ACLs that contain entries
the manager does not understand. The manager clearly cannot perform
the security service requested by an uninterpretable entry, and it
is considered a security breach to lead a client to believe that the
manager is performing a particular class of service if the manager
cannot do so.
The data structure is made up of the following components:
extension_type
The UUID of the extension type.
format_label
The format of the label, in ndr_format_t form.
num_bytes An unsigned 32-bit integer indicating the number of bytes
containing the "pickled" data.
pickled_data
The byte array containing the "pickled" data.
sec_acl_type_t
The sec_acl_type_t type differentiates among the various types of
ACLs an object can possess. Most file system objects will only
have one ACL controlling the access to that object, but objects
that control the creation of other objects (sometimes referred to
as "containers") may have more. For example, a directory can have
three different ACLs: the directory ACL, controlling access to the
directory; the initial object (or default object) ACL, which serves
as a mask when creating new objects in the directory; and the
initial directory (or default directory) ACL, which serves as a
mask when creating new directories (containers).
The sec_acl_type_t is an enumerated set containing one of the
following values:
sec_acl_type_object
The ACL refers to the specified object.
sec_acl_type_default_object
The ACL is to be used when creating objects in the
container.
sec_acl_type_default_container
The ACL is to be used when creating nested containers.
The following values are defined but not currently used. They are
available for application programs that may create an application-
specific ACL definition.
sec_acl_type_unspecified_3
sec_acl_type_unspecified_4
sec_acl_type_unspecified_5
sec_acl_type_unspecified_6
sec_acl_type_unspecified_7
sec_acl_printstring_t
A sec_acl_printstring_t structure contains a printable representa-
tion for a permission in a sec_acl_permset_t permission set. This
allows a generic ACL editing tool to be used for application-
specific ACLs. The tool need not know the printable representation
for each permission bit in a given permission set. The
sec_acl_get_printstring() function will query an ACL manager for
the print strings of the permissions it supports.
The structure consists of three components:
printstring
A character string of maximum length
sec_acl_printstring_len describing the printable
representation of a specified permission.
helpstring
A character string of maximum length
sec_acl_printstring_help_len containing some text that may
be used to describe the specified permission.
permissions
A sec_acl_permset_t permission set describing the
permissions that will be represented with the specified
print string.
sec_acl_component_name_t
This type is a pointer to a character string, to be used to specify
the entity a given ACL is protecting.
CONSTANTS
The following constants are used in sec_acl_ calls:
sec_acl_default_handle
The value of an unbound ACL manager handle.
sec_rgy_acct_key_t Constants
The following 32-bit integer constants are used with the
sec_rgy_acct_key_t data type:
sec_rgy_acct_key_none
Invalid key.
sec_rgy_acct_key_person
The person name alone is enough.
sec_rgy_acct_key_group
The person and group names are both necessary for the
account abbreviation.
sec_rgy_acct_key_org
The person, group, and organization names are all
necessary.
sec_rgy_acct_key_last
Key values must be less than this constant.
sec_rgy_pname_t_size
The maximum number of characters in a sec_rgy_pname_t.
sec_acl_permset_t Constants
The following constants are defined for use with the
sec_acl_permset_t data type:
sec_acl_perm_read
The ACL allows read access to the protected object.
sec_acl_perm_write
The ACL allows write access to the protected object.
sec_acl_perm_execute
The ACL allows execute access to the protected object.
sec_acl_perm_owner
The ACL allows owner-level access to the protected object.
sec_acl_perm_insert
The ACL allows insert access to the protected object.
sec_acl_perm_delete
The ACL allows delete access to the protected object.
sec_acl_perm_test
The ACL allows access to the protected object only to the
extent of being able to test for existence.
sec_acl_perm_unused_00000080 - sec_acl_perm_unused_0x80000000
The bits from 0x00000080 to 0x80000000 are not used by
the conventional ACL permission set. Constants have
been defined so application programs can easily use
these bits for extended ACLs.
sec_acl_printstring_len
The maximum length of the printable representation of an ACL permis-
sion. (See sec_acl_printstring_t.)
sec_acl_printstring_help_len
The maximum length of a help message to be associated with a
supported ACL permission. (See sec_acl_printstring_t.)
FILES
SYS$COMMON:[DCE$LIBRARY]ACLBASE.IDL
The idl file from which aclbase.h was derived.
3.6 – KEY_MANAGEMENT_API_DATA_TYPES
NOTES
Key management operations that take a keydata argument expect a pointer
to a sec_passwd_rec_t structure, and those that take a keytype argument
(void *) expect a pointer to a sec_passwd_type_t. Key management
operations that yield a keydata argument as output set the pointer to
an array of sec_passwd_rec_t. (The array is terminated by an element
with a key type of sec_passwd_none.)
Operations that take a keydata argument expect a pointer to a
sec_passwd_rec_t structure. Operations that yield a keydata argument
as output set the pointer to an array of sec_passwd_rec_t. (The array
is terminated by an element with key type sec_passwd_none.) Operations
that take a keytype argument (void *) expect a pointer to a
sec_passwd_type_t.
SYNOPSIS
#include <dce/keymgmt.h>
DATA TYPES
An enumerated set describing the currently supported key types. The
possible values are:
Indicates no key types are supported.
Indicates that the key is a printable string of data.
Indicates that the key is DES encrypted data.
sec_passwd_rec_t
A structure containing either a plaintext password or a preencrypted
buffer of password data. The sec_passwd_rec_t structure consists of
three components:
version_number
The version number of the password.
pepper A character string combined with the password before an
encryption key is derived from the password.
key A structure consists of the following components:
key_type
The key type can be the following:
sec_passwd_plain
Indicates that a printable string of data is
stored in plain.
sec_passwd_des
Indicates that an array of data is stored in
des_key.
tagged_union
A structure specifying the password. The value of
the structure depends on key_type. If key_type is
sec_passwd_plain, structure contains plain, a
character string. If key_type is sec_passwd_des,
the structure contains des_key, a DES key of type
sec_passwd_des_key_t.
sec_passwd_version_t
An unsigned 32-bit integer that defines the password version number.
You can supply a version number or a 0 for no version number. If
you supply the constant sec_passwd_c_version_none, the Security
service supplies a system-generated version number.
A 32-bit unsigned integer whose purpose is to indicate the authenti-
cation service in use, since a server may have different keys for
different levels of security. The possible values of this data type
and their meanings are as follows:
rpc_c_authn_none
No authentication.
rpc_c_authn_dce_private
DCE private key authentication (an implementation of the
Kerberos system).
rpc_c_authn_dce_public
DCE public key authentication (reserved for future use).
Constants
There are no constants specially defined for use with the key management
API.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which keymgmt.h was derived.
3.7 – ID_MAPPING_API_DATA_TYPES
SYNOPSIS
#include <dce/secidmap.h>
DATA TYPES
No special data types are defined for the ID Mapping API.
CONSTANTS
No special constants are defined for the ID Mapping API.
FILES
SYS$COMMON:[DCE$LIBRARY]SECIDMAP.IDL
The idl file from which secidmap.h was derived.
3.8 – PASSWORD_MANAGEMENT_API_DATA_TYPES
SYNOPSIS
#include <dce/sec_pwd_mgmt.h>
DATA TYPES
The following data types are used in sec_pwd_mgmt_ calls:
A pointer to an opaque handle consisting of password management
information about a principal. It is returned by
sec_pwd_mgmt_setup().
CONSTANTS
There are no constants specially defined for use with the Password
Management API.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_PWD_MGMT.IDL
The idl file from which sec_pwd_mgmt.h was derived.
4 – API Routines
4.1 – rdacl_get_access
NAME
rdacl_get_access - Reads a privilege attribute certificate
SYNOPSIS
#include <dce/rdaclif.h>
void rdacl_get_access(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_acl_permset_t *net_rights,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the object whose ACL is to be accessed.
component_name
A character string containing the name of the target object.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
Output
net_rights
The output list of access rights, in sec_acl_permset_t form.
This is a 32-bit set of permission flags supported by the
manager type.
status A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The rdacl_get_access() routine determines the complete extent of access
to the specified object by the calling process. Although the
rdacl_test_access() routines are the preferred method of testing access,
this routine is useful for implementing operations like the conventional
UNIX access function.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In order
to write an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the server
side of this interface. Test server code is included as a sample
implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
sec_acl_invalid_manager_type
The manager type is not valid.
sec_acl_invalid_acl_type
The ACL type is not valid.
sec_acl_not_authorized
The requested operation is not allowed.
sec_acl_object_not_found
The requested object could not be found.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
rdacl_test_access
4.2 – rdacl_get_manager_types
NAME
rdacl_get_manager_types - Lists the types of ACLs protecting an object
SYNOPSIS
#include <dce/rdaclif.h>
void rdacl_get_manager_types(
handle_t h,
sec_acl_component_name_t component_name,
sec_acl_type_t sec_acl_type,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_types,
uuid_t manager_types[],
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object.
component_name
A character string containing the name of the target object.
sec_acl_type
The ACL type. The sec_acl_type_t data type distinguishes the
various types of ACLs an object can possess for a given manager
type. The possible values are as follows:
+ sec_acl_type_object
+ sec_acl_type_default_object
+ sec_acl_type_default_container
size_avail
An unsigned 32-bit integer containing the allocated length of the
manager_types[] array.
Output
size_used
An unsigned 32-bit integer containing the number of output
entries returned in the manager_types[] array.
num_types
An unsigned 32-bit integer containing the number of types
returned in the manager_types[] array. This is always equal
to size_used.
manager_types[]
An array of length size_avail to contain UUIDs (of type uuid_t)
identifying the different types of ACL managers protecting the
target object.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The rdacl_get_manager_types() routine returns a list of the types of
ACLs protecting an object. For example, in addition to the regular file
system ACL, a file representing the stable storage of some database
could have an ACL manager that supported permissions allowing database
updates only on certain days of the week.
ACL editors and browsers can use this operation to determine the ACL
manager types that a particular reference monitor is using to protect a
selected entity. Then, using the rdacl_get_printstring() routine, they
can determine how to format for display the permissions supported by a
specific manager.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In order
to write an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the server
side of this interface. Test server code is included as a sample
implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
rdacl_get_printstring
4.3 – rdacl_get_mgr_types_semantics
NAME
rdacl_get_manager_types_semantics - Lists the ACL manager types
protecting an object and the
POSIX semantics supported by
each manager type
SYNOPSIS
#include <dce/rdaclif.h>
void rdacl_get_mgr_types_semantics(
handle_t h,
sec_acl_component_name_t component_name,
sec_acl_type_t sec_acl_type,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_types,
uuid_t manager_types[],
sec_acl_posix_semantics_t posix_semantics[],
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object.
component_name
A character string containing the name of the target object.
sec_acl_type
The ACL type used to limit the function's output to ACL managers
that control the specified types of ACLs. The possible values
are as follows:
+ sec_acl_type_object - Object ACL, the ACL controlling access
to an object.
+ sec_acl_type_default_object - Initial Object ACL, the default
ACL for objects created in a container object.
+ sec_acl_type_default_container - Initial Container ACL, the
default ACL for containers created in a container object.
size_avail
An unsigned 32-bit integer containing the allocated length of the
manager_types[] and the posix_semantics[] arrays.
Output
size_used
An unsigned 32-bit integer containing the number of output
entries returned in the manager_types[] array.
num_types
An unsigned 32-bit integer containing the number of types
returned in the manager_types[] array. This is always equal
to size_used.
manager_types[]
An array of length size_avail containing the returned UUIDs (of
type uuid_t) identifying the different ACL manager types
protecting the target object.
posix_semantics[]
An array of length size_avail containing the POSIX semantics (of
type sec_acl_posix_semantics_t) that are supported by each
returned ACL manager type.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The rdacl_get_manager_types_semantics() routine returns a list of the
ACL manager types protecting an object and a list of the POSIX semantics
supported by those ACL manager types. Access to an object can be
controlled by multiple ACL manager types. For example, access to a file
representing the stable storage of a database could be controlled by two
ACL manager types each with completely different sets of permissions:
one to provide standard file system access (read, write, execute, etc.)
and one to provide access that allows database updates only on certain
days of the week.
ACL editors and browsers can use this operation to determine the ACL
manager types that a particular reference monitor is using to protect a
selected entity. Then, using the rdacl_get_printstring() routine, they
can determine how to format for display the permissions supported by a
specific manager.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In order
to write an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the server
side of this interface. Test server code is included as a sample
implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
rdacl_get_printstring
4.4 – rdacl_get_printstring
NAME
rdacl_get_printstring - Returns printable ACL strings
SYNOPSIS
#include <dce/rdaclif.h>
void rdacl_get_printstring(
handle_t h,
uuid_t *manager_type,
unsigned32 size_avail,
uuid_t *manager_type_chain,
sec_acl_printstring_t *manager_info,
boolean32 *tokenize,
unsigned32 *total_num_printstrings,
unsigned32 *size_used,
sec_acl_printstring_t printstrings[],
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
rdacl_get_manager_types() to acquire a list of the manager
types protecting a given object.
size_avail
An unsigned 32-bit integer containing the allocated length of the
printstrings[] array.
Output
manager_type_chain
If the target object ACL contains more than 32 permission bits,
multiple manager types are used, one for each 32-bit wide "slice"
of permissions. The UUID returned in manager_type_chain refers
to the next ACL manager in the chain. If there are no more ACL
managers for this ACL, uuid_nil is returned.
manager_info
Provides a name and helpstring for the given ACL manager.
tokenize
When FALSE this variable indicates that the returned permission
printstrings are unambiguous and therefore may be concatenated
when printed without confusion. When TRUE, however, this property
does not hold, and the strings need to be separated when printed
or passed.
total_num_printstrings
An unsigned 32-bit integer containing the total number of
permission printstrings supported by this ACL manager type.
size_used
An unsigned 32-bit integer containing the number of permission
entries returned in the printstrings[] array.
printstrings[]
An array of permission printstrings of type sec_acl_printstring_t.
Each entry of the array is a structure containing three
components:
printstring
A character string of maximum length sec_acl_printstring_len
containing the printable representation of a specified
permission.
helpstring
A character string of maximum length
sec_acl_printstring_help_len containing some text that can
be used to describe the specified permission.
permissions
A sec_acl_permset_t permission set describing the
permissions that are to be represented with the companion
printstring. The array consists of one such entry for
each permission supported by the ACL manager identified
by manager_type.
status
A pointer to the completion status. On successful completion, the
routine returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The rdacl_get_printstring() routine returns an array of printable
representations (called printstrings) for each permission bit or
combination of permission bits the specified ACL manager will support.
The ACL manager type specified must be one of the types indicated by
the ACL handle.
In addition to returning the printstrings, this routine also returns
instructions about how to print the strings. When the tokenize variable
is set to FALSE, a print string might be r or w, which could be
concatenated in the display as rw without any confusion. However, when
the tokenize variable is TRUE, it implies the printstrings might be of
a form like read or write, which must be displayed separated by spaces
or colons or something.
In any list of permission printstrings, there may appear to be some
redundancy. ACL managers often define aliases for common permission
combinations. By convention, however, simple entries need to appear
at the beginning of the printstrings[] array, and combinations need to
appear at the end.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In
order to write an ACL manager, a programmer must implement the entire
rdacl interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the
server side of this interface. Test server code is included as a
sample implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not among those referenced by
the input handle.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
rdacl_get_manager_types
4.5 – rdacl_get_referral
NAME
rdacl_get_referral - Gets a referral to an ACL update site
SYNOPSIS
#include <dce/rdaclif.h>
void rdacl_get_referral(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_acl_type_t sec_acl_type,
sec_acl_tower_set_t *towers[],
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object.
component_name
A character string containing the name of the target object.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
sec_acl_type
The ACL type. The sec_acl_type_t data type distinguishes the
various types of ACLs an object can possess for a given manager
type. The possible values are as follows:
+ sec_acl_type_object
+ sec_acl_type_default_object
+ sec_acl_type_default_container
Output
towers[]
A pointer to address information indicating an ACL update site.
This information, obtained from the RPC runtime, is used by the
client-side code to construct a new ACL binding handle indicating
a site that will not return the sec_acl_site_readonly error.
The sec_acl_tower_set_t structure contains an array of towers
(called towers[]) and an unsigned 32-bit integer indicating the
number of array elements (called count). This type enables the
client to pass in an unallocated array of towers and have the
server allocate the correct amount.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The rdacl_get_referral() routine obtains a referral to an ACL update
site. This function is used when the current ACL site yields a
sec_acl_site_readonly error. Some replication managers will require all
updates for a given object to be directed to a given replica. If
clients of the generic ACL interface know they are dealing with an
object that is replicated in this way, this function allows them to
recover from the problem and rebind to the proper update site. The DCE
network registry, for example, is replicated this way.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In
order to write an ACL manager, a programmer must implement the entire
rdacl interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the server
side of this interface. Test server code is included as a sample
implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
4.6 – rdacl_lookup
NAME
rdacl_lookup - Returns the ACL for an object
SYNOPSIS
#include <dce/rdaclif.h>
void rdacl_lookup(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_acl_type_t sec_acl_type,
sec_acl_result_t *result);
PARAMETERS
Input
h A handle referring to the target object.
component_name
A character string containing the name of the target object.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
sec_acl_type
The ACL type. The sec_acl_type_t data type distinguishes the
various types of ACLs an object can possess for a given
manager type. The possible values are as follows:
+ sec_acl_type_object
+ sec_acl_type_default_object
+ sec_acl_type_default_container
Output
result A pointer to a tagged union of type sec_acl_result_t. The tag
is the completion status, result.st. If result.st is equal to
error_status_ok, the union contains an ACL. Otherwise, the
completion status indicates an error, and the union is empty.
If the call returned successfully, the
result.tagged_union.sec_acl_list_t structure contains a
sec_acl_list_t. This data type is an array of pointers to
sec_acl_ts that define ACLs. If the permission set of the
returned ACL is 32 bits or smaller, sec_acl_list_t points to
only one sec_acl_t. If the permission set of the returned ACL
is larger than 32 bits, multiple sec_acl_ts are used to hold
them, and the sec_acl_list_t points to multiple sec_acl_ts.
DESCRIPTION
The rdacl_lookup() routine loads into memory a copy of an object's ACL
corresponding to the specified manager type. The routine returns a
pointer to the ACL. This routine is only used by ACL editors and
browsers; an application would use sec_acl_test_access() or
sec_acl_test_access_on_behalf() to process the contents of an ACL.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In order
to write an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the server
side of this interface. Test server code is included as a sample
implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
sec_acl_cant_allocate_memory
The requested operation requires more memory than is avail-
able.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_test_access
sec_acl_test_access_on_behalf
4.7 – rdacl_replace
NAME
rdacl_replace - Replaces an ACL
SYNOPSIS
#include <dce/rdaclif.h>
void rdacl_replace(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_acl_type_t sec_acl_type,
sec_acl_list_t *sec_acl_list,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object.
component_name
A character string containing the name of the target object.
manager_type
A pointer to the UUID identifying the type of the ACL manager in
question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
sec_acl_type
The ACL type. The sec_acl_type_t data type distinguishes the
various types of ACLs an object can possess for a given manager
type. The possible values are as follows:
+ sec_acl_type_object
+ sec_acl_type_default_object
+ sec_acl_type_default_container
sec_acl_list
The new ACL to use for the target object. This is represented by
a pointer to the sec_acl_list_t structure containing the complete
Access Control List. An ACL contains a list of ACL entries, the
UUID of the default cell where authentication takes place
(foreign entries in the ACL contain the name of their parent
cell), and the UUID of the ACL manager to interpret the list.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The rdacl_replace() routine replaces the ACL indicated by the input
handle with the information in the sec_acl_list parameter. ACLs are
thought of as immutable, and in order to modify them, an editing
application must read an entire ACL (using the sec_acl_lookup()
routine), modify it as needed, and replace it using this routine.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In
order to write an ACL manager, a programmer must implement the entire
rdacl interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the server
side of this interface. Test server code is included as a sample
implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_lookup
4.8 – rdacl_test_access
NAME
rdacl_test_access - Tests access to an object
SYNOPSIS
#include <dce/rdaclif.h>
boolean32 rdacl_test_access(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_acl_permset_t desired_permset,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object.
component_name
A character string containing the name of the target object.
manager_type
A pointer to the UUID identifying the type of the ACL manager in
question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
desired_permset
A permission set in sec_acl_permset_t form containing the desired
privileges. This is a 32-bit set of permission flags supported by
the manager type.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The rdacl_test_access() routine determines if the specified ACL contains
entries granting privileges to the calling process matching those in
desired_permset. An application generally only inquires after the
minimum set of privileges needed to accomplish a specific task.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In
order to write an ACL manager, a programmer must implement the entire
rdacl interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the server
side of this interface. Test server code is included as a sample
implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
rdacl_test_access_on_behalf
4.9 – rdacl_test_access_on_behalf
NAME
rdacl_test_access_on_behalf - Tests access to an object on behalf of
another process
SYNOPSIS
#include <dce/rdaclif.h>
boolean rdacl_test_access_on_behalf(
handle_t h,
sec_acl_component_name_t component_name,
uuid_t *manager_type,
sec_id_pac_t *subject,
sec_acl_permset_t desired_permset,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object.
component_name
A character string containing the name of the target object.
manager_type
A pointer to the UUID identifying the type of the ACL manager in
question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
subject
A Privilege Attribute Certificate (PAC) for the subject process.
The PAC contains the name and UUID of the principal and parent
cell of the subject process, as well as a list of any groups to
which it belongs. The PAC also contains a flag (named
authenticated). When set, it indicates that the certificate was
obtained from an authenticated source. When not set, the
certificate must not be trusted. (The field is FALSE when it was
obtained from the rpc_auth layer and the protect level was set to
rpc_c_protect_level_none. This indicates that no authentication
protocol was actually used in the remote procedure call; the
identity was simply transmitted from the caller to the callee.
If an authentication protocol was used, then the flag is set to
TRUE.) A server uses rpc_binding_inq_auth_client() to acquire a
certificate for the client process.
desired_permset
A permission set in sec_acl_permset_t form containing the desired
privileges. This is a 32-bit set of permission flags supported
by the manager type.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The rdacl_test_access_on_behalf() routine determines if the specified
ACL contains entries granting privileges to the subject, a process
besides the calling process, matching those in desired_permset. This
routine succeeds only if the access is available to both the caller
process as well as the subject identified in the call. An application
will generally only inquire after the minimum set of privileges needed
to accomplish a specific task.
NOTES
This call is not intended to be used by application programs. The
sec_acl Application Programming Interface (API) provides all the
functionality necessary to use the ACL facility. This reference page
is provided for programmers who wish to write an ACL manager. In order
to write an ACL manager, a programmer must implement the entire rdacl
interface.
This network interface is called on the client side via the sec_acl
local interface. Developers are responsible for implementing the server
side of this interface. Test server code is included as a sample
implementation.
FILES
SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
The idl file from which dce/rdaclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
rdacl_test_access
rpc_binding_inq_auth_client
4.10 – sec_acl_bind
NAME
sec_acl_bind - Returns a handle for an object's ACL
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_bind(
unsigned char *entry_name,
boolean32 bind_to_entry,
sec_acl_handle_t *h,
error_status_t *status);
PARAMETERS
Input
entry_name
The name of the target object. Subsequent ACL operations using the
returned handle will affect the ACL of this object.
bind_to_entry
Bind indicator, for use when entry_name identifies both an entry
in the global namespace and an actual object. A TRUE value binds
the handle to the entry in the namespace, while FALSE binds the
handle to the actual object.
Output
h A pointer to the sec_acl_handle_t variable to receive the returned
ACL handle. The other sec_acl routines use this handle to refer
to the ACL for the object specified with entry_name.
status
A pointer to the completion status. On successful completion, the
routine returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_acl_bind() routine returns a handle bound to the indicated
object's ACL. This routine is central to all the other sec_acl
routines, each of which requires this handle to identify the ACL on
which to operate.
NOTES
If the specified name is both an actual object, and an entry in the
global namespace, there are two ACLs associated with it. For example,
in addition to the ACL normally attached to file system objects, the
root directory of a file system has an ACL corresponding to its entry
in the global namespace. This controls access by outsiders to the entire
file system, whereas the resident ACL for the root directory only
controls access to the directory and, by inheritance, its sub-
directories. The ambiguity must be resolved with the bind_to_entry
parameter.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
sec_acl_object_not_found
The requested object could not be found.
sec_acl_no_acl_found
There is no ACL associated with the specified object.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
4.11 – sec_acl_bind_to_addr
NAME
sec_acl_bind_to_addr - Returns a handle to an object identified by
its network address
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_bind_to_addr(
unsigned char *site_addr,
sec_acl_component_name_t component_name,
sec_acl_handle_t *h,
error_status_t *status);
PARAMETERS
Input
site_addr
An RPC string binding to the fully qualified network address of
the target object.
component_name
The name of the target object. Subsequent ACL operations using
the returned handle will affect the ACL of this object.
Output
h A pointer to the sec_acl_handle_t variable to receive the
returned ACL handle. The other sec_acl routines use this
handle to refer to the ACL for the object specified with
entry_name.
status A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_acl_bind_to_addr() routine returns a handle bound to the
indicated object's ACL manager. This routine and the sec_acl_bind()
routine are central to all the other sec_acl routines, each of which
requires a handle to identify the ACL on which to operate.
This routine differs from sec_acl_bind() in that it binds to the network
address of the target object, rather than to a cell namespace entry.
Therefore, unlike sec_acl_bind(), it is possible to pass
sec_acl_bind_to_addr() a null string as a component name and to bind
with a nonexistent name. The purpose of this call is to eliminate the
necessity of looking up an object's name. To validate the name, use
sec_acl_bind().
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
sec_acl_object_not_found
The requested object could not be found.
sec_acl_no_acl_found
There is no ACL associated with the specified object.
sec_acl_unable_to_authenticate
The call could not authenticate to the server that manages
the target object's ACL.
sec_acl_bind_error
The call could not bind to the requested site.
sec_acl_invalid_site_name
The site_addr parameter is invalid.
sec_acl_cant_allocate_memory
Memory allocation failure.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
4.12 – sec_acl_calc_mask
NAME
sec_acl_calc_mask - Returns the sec_acl_type_mask_obj entry for the
specified ACL list
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_calc_mask(
sec_acl_list_t *sec_acl_list,
error_status_t *status);
PARAMETERS
Input/Output
*sec_acl_list
A pointer to a sec_acl_type_t the specifies the number of ACLs of
each ACL type. The sec_acl_type_t data type distinguishes between
the various types of ACLs an object can possess for a given
manager. In the file system, for example, most objects have only
one ACL, controlling the access to that object, but objects that
control the creation of other objects (sometimes referred to as
"containers") may have more. A directory, for example, can have
ACLs to be used as initial values when member objects are created.
Do not confuse ACL types with the permissions corresponding to
different ACL manager types or with the ACL manager types them-
selves.
Output
status
A pointer to the completion status. On successful completion, the
routine returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_acl_calc_mask() routine calculates and sets the
sec_acl_e_type_mask_obj entry of the specified ACL list. The value of
the sec_acl_e_type_mask_obj entry is the union of the permissions of all
ACL entries that refer to members of the File Group Class.
This operation is performed locally, within the client. The function
does not check to determine if the manager to which the specified ACL
list will be submitted supports the sec_acl_e_type_mask_obj entry type.
The calling application must determine whether to call this routine,
after obtaining the required, if any, POSIX semantics, via the
sec_acl_get_mgr_types_semantics() routine.
NOTES
This call is provided in source code form.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
sec_acl_cant_allocate_memory
Requested operation requires more memory than is available.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
4.13 – sec_acl_get_access
NAME
sec_acl_get_access - Lists the access (permission set) that the caller
has for an object
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_get_access(
sec_acl_handle_t h,
uuid_t *manager_type,
sec_acl_permset_t *net_rights,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the object whose ACL is to be accessed.
Use sec_acl_bind() to create this handle.
manager_type
A pointer to the UUID identifying the manager type of the ACL in
question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
Output
net_rights
The output list of access rights in sec_acl_permset_t form.
This is a 32-bit set of permission flags supported by the
manager type.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_acl_get_access() routine determines the complete extent of
access to the specified object by the calling process. Although the
sec_acl_test_access() and sec_acl_test_access_on_behalf() routines are
the preferred method of testing access, this routine is useful for
implementing operations like the conventional UNIX access function.
Permissions Required
The sec_acl_get_access() routine requires at least one permission of any
kind on the object for which the access is to be returned.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_acl_test_access
sec_acl_test_access_on_behalf
4.14 – sec_acl_get_error_info
NAME
sec_acl_get_error_info - Returns error information from an ACL handle
SYNOPSIS
#include <dce/daclif.h>
error_status_t sec_acl_get_error_info(
sec_acl_handle_t h);
PARAMETERS
Input
h A handle referring to the target ACL. The handle is bound to the
ACL with the sec_acl_bind() routine, which also specifies the
name of the object to which the target ACL belongs.
DESCRIPTION
The sec_acl_get_error_info() routine returns error information from the
specified ACL handle.
During a call to a routine in the sec_acl Application Programming
Interface (API), error codes received from the RPC runtime or other
APIs are saved in the ACL handle and a corresponding error code from
the sec_acl set is passed back by the ACL API. The
sec_acl_get_error_info() routine returns the last error code stored
in the ACL handle for those clients who need to know exactly what went
wrong.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
RETURN VALUES
This routine returns a value of type error_status_t, indicating the
cause of the last error issued by the RPC runtime.
ERRORS
sec_acl_invalid_handle
The ACL handle specified by sec_acl_handle_t is invalid.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_lookup
4.15 – sec_acl_get_manager_types
NAME
sec_acl_get_manager_types - Lists the manager types of the ACLs
protecting an object
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_get_manager_types(
sec_acl_handle_t h,
sec_acl_type_t sec_acl_type,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_types,
uuid_t manager_types[],
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object. Use sec_acl_bind() to
create this handle.
sec_acl_type
The ACL type. The sec_acl_type_t data type distinguishes the
various types of ACLs an object can possess for a given manager
type. The possible values are as follows:
+ sec_acl_type_object
+ sec_acl_type_default_object
+ sec_acl_type_default_container
size_avail
An unsigned 32-bit integer containing the allocated length of the
manager_types[] array.
Output
size_used
An unsigned 32-bit integer containing the number of output
entries returned in the manager_types[] array.
num_types
An unsigned 32-bit integer containing the number of types
returned in the manager_types[] array. This may be greater
than size_used if there was not enough space allocated in the
manager_types[] array for all the manager types.
manager_types[]
An array of length size_avail to contain UUIDs (of type uuid_t)
identifying the different types of ACL managers protecting the
target object.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_acl_get_manager_types() routine returns a list of the manager
types of ACLs of type sec_acl_type that are protecting the object
identified by h. For example, in addition to the regular file system
ACL, a file representing the stable storage of some database could have
an ACL manager that supported permissions allowing database updates
only on certain days of the week.
ACL editors and browsers can use this operation to determine the ACL
manager types that a particular reference monitor is using to protect a
selected entity. Then, using the sec_acl_get_printstring() routine, they
can determine how to format for display the permissions supported by a
specific manager.
Permissions Required
The sec_acl_get_manager_types() routine requires at least one permission
of any kind on the object for which the ACL manager types are to be
returned.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_get_printstring
4.16 – sec_acl_get_manager_types_semantics
NAME
sec_acl_get_mgr_types_semantics - Lists the manager types of the ACLs
protecting an object
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_get_mgr_types_semantics(
sec_acl_handle_t h,
sec_acl_type_t sec_acl_type,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_types,
uuid_t manager_types[],
sec_acl_posix_semantics_t posix_semantics[],
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object. Use sec_acl_bind() to
create this handle.
sec_acl_type
The ACL type. The sec_acl_type_t data type distinguishes the
various types of ACLs an object can possess for a given manager
type. The possible values are as follows:
+ sec_acl_type_object
+ sec_acl_type_default_object
+ sec_acl_type_default_container
size_avail
An unsigned 32-bit integer containing the allocated length of
the manager_types[] array.
Output
size_used
An unsigned 32-bit integer containing the number of output
entries returned in the manager_types[] array.
num_types
An unsigned 32-bit integer containing the number of types
returned in the manager_types[] array. This may be greater
than size_used if there was not enough space allocated in the
manager_types[] array for all the manager types.
manager_types[]
An array of length size_avail to contain UUIDs (of type uuid_t)
identifying the different types of ACL managers protecting the
target object.
posix_semantics[]
An array of POSIX semantics supported by each manager type with
entries of type sec_acl_posix_semantics_t.
status A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_acl_get_mgr_types_semantics() routine returns a list of the
manager types of ACLs of type sec_acl_type that are protecting the
object identified by h. For example, in addition to the regular file
system ACL, a file representing the stable storage of some database
could have an ACL manager that supported permissions allowing database
updates only on certain days of the week.
ACL editors and browsers can use this operation to determine the ACL
manager types that a particular reference monitor is using to protect a
selected entity. Then, using the sec_acl_get_printstring() routine, they
can determine how to format for display the permissions supported by a
specific manager.
Permissions Required
The sec_acl_get_mgr_types_semantics() routine requires at least one
permission of any kind on the object for which the ACL manager types
are to be returned.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_get_printstring
4.17 – sec_acl_get_printstring
NAME
sec_acl_get_printstring - Returns printable ACL strings
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_get_printstring(
sec_acl_handle_t h,
uuid_t *manager_type,
unsigned32 size_avail,
uuid_t *manager_type_chain,
sec_acl_printstring_t *manager_info,
boolean32 *tokenize,
unsigned32 *total_num_printstrings,
unsigned32 *size_used,
sec_acl_printstring_t printstrings[],
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object. Use sec_acl_bind() to
create this handle.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
size_avail
An unsigned 32-bit integer containing the allocated length of the
printstrings[] array.
Output
manager_type_chain
If the target object ACL contains more than 32 permission bits,
multiple manager types are used, one for each 32-bit wide
"slice" of permissions. The UUID returned in manager_type_chain
refers to the next ACL manager in the chain. If there are no
more ACL managers for this ACL, uuid_nil is returned.
manager_info
Provides a name and helpstring for the given ACL manager.
tokenize
When FALSE, this variable indicates that the returned permission
printstrings are unambiguous and therefore may be concatenated
when printed without confusion. When TRUE, however, this
property does not hold, and the strings need to be separated
when printed or passed.
total_num_printstrings
An unsigned 32-bit integer containing the total number of
permission printstrings supported by this ACL manager type.
size_used
An unsigned 32-bit integer containing the number of permission
entries returned in the printstrings[] array.
printstrings[]
An array of permission printstrings of type
sec_acl_printstring_t. Each entry of the array is a
structure containing the following three components:
printstring
A character string of maximum length
sec_acl_printstring_len describing the printable
representation of a specified permission.
helpstring
A character string of maximum length
sec_acl_printstring_help_len containing some text that
can be used to describe the specified permission.
permissions
A sec_acl_permset_t permission set describing the
permissions that are represented with the companion
printstring. The array consists of one such entry
for each permission supported by the ACL manager
identified by manager_type.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_acl_get_printstring() routine returns an array of printable
representations (called "printstrings") for each permission bit or
combination of permission bits the specified ACL manager supports.
The ACL manager type specified must be one of the types protecting
the object indicated by h.
In addition to returning the printstrings, this routine also returns
instructions about how to print the strings. When the tokenize variable
is set to FALSE, a printstring might be r or w, which could be
concatenated in the display as rw without any confusion. However, when
the tokenize variable is TRUE, it implies the printstrings might be of
a form like read or write, which must be displayed separated by spaces
or colons or something.
In any list of permission printstrings, there may appear to be some
redundancy. ACL managers often define aliases for common permission
combinations. By convention, however, simple entries should appear
at the beginning of the printstrings[] array, and combinations should
appear at the end.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not among those referenced
by the input handle.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_get_manager_types
4.18 – sec_acl_lookup
NAME
sec_acl_lookup - Returns the ACL for an object
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_lookup(
sec_acl_handle_t h,
uuid_t *manager_type,
sec_acl_type_t sec_acl_type,
sec_acl_list_t *sec_acl_list,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object. Use sec_acl_bind() to
create this handle.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
sec_acl_type
The ACL type. The sec_acl_type_t data type distinguishes the
various types of ACLs an object can possess for a given manager
type. The possible values are as follows:
+ sec_acl_type_object
+ sec_acl_type_default_object
+ sec_acl_type_default_container
Output
sec_acl_list
A pointer to the sec_acl_list_t structure to receive the complete
Access Control List. An ACL contains a list of ACL entries, the
UUID of the default cell where authentication takes place
(foreign entries in the ACL contain the name of their home cell),
and the UUID of the ACL manager to interpret the list.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_acl_lookup() routine loads into memory a copy of an object's
ACL corresponding to the specified manager type. The routine returns
a pointer to the ACL. This routine is only used by ACL editors and
browsers; an application would use sec_acl_test_access() or
sec_acl_test_access_on_behalf() to process the contents of an ACL.
Permissions Required
The sec_acl_lookup() routine requires at least one permission of any
kind on the object for which the ACL is to be returned.
NOTES
The memory containing the sec_acl_t structure for each ACL is
dynamically allocated. Use the sec_acl_release() routine to return
each ACL's memory block to the pool when an application is finished
with the ACLs.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
sec_acl_cant_allocate_memory
The requested operation requires more memory than is avail-
able.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_test_access
sec_acl_test_access_on_behalf
4.19 – sec_acl_release
NAME
sec_acl_release - Releases ACL storage
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_release(
sec_acl_handle_t h,
sec_acl_t *sec_acl,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object. Use sec_acl_bind() to
create this handle.
sec_acl
A pointer to the complete ACL associated with the target object.
Output
status
A pointer to the completion status. On successful completion, the
routine returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_acl_release() routine releases any local storage associated with
the ACL object, returning it to the pool. This is strictly a local
operation (since the storage in question is local), and has no effect on
the remote object or its ACL. The ACL handle is in the argument list
only for consistency with other sec_acl routines.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_lookup
4.20 – sec_acl_release_handle
NAME
sec_acl_release_handle - Removes an ACL handle
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_release_handle(
sec_acl_handle_t *h,
error_status_t *status);
PARAMETERS
Input
h The handle to be removed. The handle is bound to the object to
which the ACL belongs with the sec_acl_bind() routine.
Output
status
A pointer to the completion status. On successful completion, the
routine returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_acl_release_handle() routine removes the specified handle.
This is strictly a local operation, and has no effect on the remote
object or its ACL.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
4.21 – sec_acl_replace
NAME
sec_acl_replace - Replaces an ACL
SYNOPSIS
#include <dce/daclif.h>
void sec_acl_replace(
sec_acl_handle_t h,
uuid_t *manager_type,
sec_acl_type_t sec_acl_type,
sec_acl_list_t *sec_acl_list,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object. Use sec_acl_bind() to
create this handle.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
sec_acl_type
The ACL type. The sec_acl_type_t data type distinguishes the
various types of ACLs an object can possess for a given manager
type. The possible values are as follows:
+ sec_acl_type_object
+ sec_acl_type_default_object
+ sec_acl_type_default_container
sec_acl_list
The new ACL to use for the target object. This is represented by a
pointer to the sec_acl_list_t structure containing the complete
Access Control List. An ACL contains a list of ACL entries, the
UUID of the default cell where authentication will take place
(foreign entries in the ACL contain the name of their parent
cell), and the UUID of the ACL manager to interpret the list.
Output
status
A pointer to the completion status. On successful completion, the
routine returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_acl_replace() routine replaces the ACL indicated by the input
handle with the information in the sec_acl_list parameter. ACLs are
thought of as immutable, and in order to modify them, an editing
application must read an entire ACL (using the sec_acl_lookup()
routine), modify it as needed, and replace it using this routine.
Permissions Required
The sec_acl_replace() routine requires the c (control) permission on the
object for which the ACL is to be replaced.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_lookup
4.22 – sec_acl_test_access
NAME
sec_acl_test_access - Tests access to an object
SYNOPSIS
#include <dce/daclif.h>
boolean32 sec_acl_test_access(
sec_acl_handle_t h,
uuid_t *manager_type,
sec_acl_permset_t desired_permset,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object. Use sec_acl_bind() to
create this handle.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
desired_permset
A permission set in sec_acl_permset_t form containing the desired
privileges. This is a 32-bit set of permission flags supported by
the manager type.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_acl_test_access() routine determines if the specified ACL
contains entries granting privileges to the calling process matching
those in desired_permset. An application generally only inquires after
the minimum set of privileges needed to accomplish a specific task.
Permissions Required
The sec_acl_test_access() routine requires at least one permission of
any kind on the object for which the privileges are to be tested.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
RETURN VALUES
The routine returns TRUE if the calling application program is
authorized to access the target object with the privileges in
desired_permset.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_test_access_on_behalf
4.23 – sec_acl_test_access_on_behalf
NAME
sec_acl_test_access_on_behalf - Tests access to an object on behalf of
another process
SYNOPSIS
#include <dce/daclif.h>
boolean32 sec_acl_test_access_on_behalf(
sec_acl_handle_t h,
uuid_t *manager_type,
sec_id_pac_t *subject,
sec_acl_permset_t desired_permset,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the target object. Use sec_acl_bind() to
create this handle.
manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the object whose ACL is bound to the input handle.
Use this parameter to distinguish them. Use
sec_acl_get_manager_types() to acquire a list of the manager
types protecting a given object.
subject
A Privilege Attribute Certificate (PAC) for the subject process.
The PAC contains the name and UUID of the principal and cell of
the subject process, as well as a list of any groups to which it
belongs. The PAC also contains a flag (named authenticated).
When set, it indicates that the certificate was obtained from an
authenticated source. When not set, the certificate must not be
trusted. (The field is FALSE when it was obtained from the
rpc_auth layer and the protect level was set to
rpc_c_protect_level_none. This indicates that no authentication
protocol was actually used in the remote procedure call; the
identity was simply transmitted from the caller to the callee.
If an authentication protocol was used, then the flag is set to
TRUE.) If a null PAC is passed, the subject is treated as an
"anonymous user", matching only the any_other and unauthenticated
entries (if they exist) on the ACL. A server uses
rpc_binding_inq_auth_client() to acquire a certificate for the
client process.
desired_permset
A permission set in sec_acl_permset_t form containing the desired
privileges. This is a 32-bit set of permission flags supported by
the manager type.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_acl_test_access_on_behalf() routine determines if the specified
ACL contains entries that grant the privileges specified in
desired_permset to the subject process. An application generally
inquires about only the minimum set of privileges needed to accomplish
a specific task.
Permissions Required
The sec_acl_test_access_on_behalf() routine requires at least one
permission of any kind on the object for which the privileges are to
be tested. Both the calling process and the identified subject must
have permission on the object.
FILES
SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL
The idl file from which dce/daclif.h was derived.
RETURN VALUES
If the routine completes successfully (with a completion status of
error_status_ok) it returns a value of
+ TRUE if the caller has any access (at least one permission of any
kind), and the subject has the desired_permset privileges.
+ FALSE if both the caller and the subject have any access, but the
subject does not have the desired_permset privileges.
If the routine does not complete successfully, it returns a bad
completion status code and a return value of FALSE.
ERRORS
sec_acl_unknown_manager_type
The manager type selected is not an available option.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_acl_bind
sec_acl_test_access
rpc_binding_inq_auth_client
4.24 – sec_attr_trig_query
NAME
sec_attr_trig_query - Reads attributes coded with an attribute trigger
type of query
SYNOPSIS
#include <dce/sec_attr_trig.h>
void sec_attr_trig_query (
handle_t h,
sec_attr_component_name_t cell_name,
sec_attr_component_name_t component_name,
sec_attr_trig_cursor_t *cursor,
unsigned32 num_attr_keys,
unsigned32 space_avail,
sec_attr_t attr_keys[],
unsigned32 *num_returned,
sec_attr_t attrs[],
sec_attr_trig_timeval_sec_t time_to_live[],
unsigned32 *num_left,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the trigger server to be accessed Use the
trigger binding information specified in the attribute encoding
to acquire a bound handle.
cell_name
A value of sec_attr_component_name_t that identifies the cell in
which the object whose attribute is to be accessed resides.
Supply a NULL cell_name to specify the local cell (/.:).
component_name
A value of sec_attr_component_name_t that identifies the name of
the object whose attribute is to be accessed. If cell_name
specifies a foreign cell, component_name is interpreted as a
UUID in string format since the caller of this interface knows
only the UUID, not the name, of the foreign principal.
num_attr_keys
An unsigned 32-bit integer that specifies the number of elements
in the attr_keys[] array. This integer must be greater than 0.
space_avail
An unsigned 32-bit integer that specifies the size of the
attr_keys[] array.
attr_keys[]
An array of values of type sec_attr_t. For each attribute
instance, the sec_attr_t array contains an attr_id (a UUID of
type uuid_t) to identify the attribute to be queried and an
attr_value. attr_value can be used to pass in optional
information required by the attribute trigger query. If no
additional information is to be passed, set attr_value to
sec_attr_enc_void. This is actually accomplished by setting the
sec_attr_encoding_t data type to sec_attr_enc_void. The size
of the attr_keys[] array is determined by num_attr_keys.
Input/Output
cursor
A pointer to a cursor of type sec_attr_trig_cursor_t. As an input
parameter, cursor can be initialized (by the
sec_addr_trig_cursor_init routine) or uninitialized. As an output
parameter, cursor is positioned past the attributes returned in
this call.
Output
num_returned
A pointer to an unsigned 32-bit integer that specifies the number
of attribute instances returned in the attr_keys[] array.
attrs[]
An array of values of type sec_attr_t. The size of this array is
determined by the space_avail parameter and the length by the
num_returned parameter.
time_to_live[],
An array of values of type sec_attr_trig_timeval_sec_t. For
each attribute in the attrs[] array, The time_to_live[] array
specifies the time in seconds that the attribute can be safely
cached.
num_left
A pointer to an unsigned 32-bit integer that supplies the number
of attributes found but not returned because of space constraints
in the attrs[] buffer.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_attr_trig_query() routine reads attributes coded with an
attribute trigger type of query.
The sec_attr_trig_query() routine is called by the DCE attribute lookup
code for all schema entries that specify a query attribute trigger
(sec_attr_trig_type_query specified with the sec_attr_trig_type_flags_t
data type). The attribute query code passes the sec_attr_trig_query()
input parameters to a user-written query attribute trigger server and
receives the output parameters back from the server. Although generally
this routine it is not called directly, this reference page is provided
for users who are writing the attribute trigger servers that will
receive sec_attr_trig_query() input and supply its output.
Multi-valued attributes are returned as independent attribute instances
sharing the same attribute UUID. A read of an attribute set returns all
instances of members of the set; the attribute set instance is not
returned.
For objects in the local cell, set the cell_name parameter to null, and
the component_name parameter to specify the object's name.
For objects in a foreign cell, set the cell_name parameter to identify
the name of the foreign cell, and the component_name parameter to the
UUID in string format that identifies the object in the foreign cell.
The cursor parameter specifies a cursor of type sec_attr_trig_cursor_t
that establishes the point in the attribute list at which to start
processing the query. Use the sec_attr_trig_cursor_init function to
initialize a list cursor. If cursor is uninitialized, the server begins
processing the query at the first attribute that satisfies the search
criteria. Note that generally, sec_attr_trig_cursor_init function makes
a remote call to the specified server. To initialize the cursor without
making this remote call, set the sec_attr_trig_cursor_init function
valid parameter to 0.
The num_left parameter contains the number of attributes that were found
but could not be returned because of space constraints of the attrs[]
array. (Note that this number may be inaccurate if the target server
allows updates between successive queries.) To obtain all of the
remaining attributes, set the size of the attrs[] array so that it is
large enough to hold the number of attributes listed in num_left.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_ATTR_TRIG.IDL
The idl file from which sec_attr_trig.h was derived.
ERRORS
not_all_available
unauthorized
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_attr_trig_cursor_init
sec_attr_trig_update
4.25 – sec_attr_trig_update
NAME
sec_attr_trig_update - For attributes coded with an attribute trigger
type of update, passes attribute updates to an
update attribute trigger server for evaluation
SYNOPSIS
#include <dce/sec_attr_trig.h>
void sec_attr_trig_update (
handle_t h,
sec_attr_component_name_t cell_name,
sec_attr_component_name_t component_name,
unsigned32 num_to_write,
unsigned32 space_avail,
sec_attr_t in_attrs[],
unsigned32 *num_returned,
sec_attr_t out_attrs[],
unsigned32 *num_left,
signed32 *failure_index,
error_status_t *status);
PARAMETERS
Input
h A handle referring to the trigger server to be accessed. Use the
trigger binding information specified in the attribute encoding
to acquire a bound handle.
cell_name
A value of sec_attr_component_name_t that identifies the cell
in which the object whose attribute is to be accessed resides.
Supply a NULL cell_name to specify the local cell (/.:).
component_name
A value of sec_attr_component_name_t that identifies the name of
the object whose attribute is to be accessed. If cell_name
specifies a foreign cell, component_name is interpreted as a
UUID in string format since the caller of this interface knows
only the UUID, not the name, of the foreign principal.
num_to_write
An unsigned 32-bit integer that specifies the number of elements
in the in_attrs array. This integer must be greater than 0.
space_avail
An unsigned 32-bit integer that specifies the size of the
out_attrs array.
in_attrs[]
An array of values of type sec_attr_t that specifies the
attribute instances to be written. The size of in_attrs[]
is determined by num_to_write.
Output
num_returned
A pointer to an unsigned 32-bit integer that specifies the number
of attribute instances returned in the out_attrs[] array.
out_attrs[]
An array of values of type sec_attr_t. These values, supplied by
the update attribute trigger server, are in a form suitable for
storage in the registry database.
num_left
A pointer to an unsigned 32-bit integer that supplies the number
of attributes that were found but not returned because of space
constraints in the out_attrs[] buffer.
failure_index
In the event of an error, failure_index is a pointer to the
element in the in_attrs[] array that caused the update to fail.
If the failure cannot be attributed to a specific attribute, the
value of failure_index is -1.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_attr_trig_update() routine passes attributes coded with an
attribute trigger type of update to a user-written update attribute
trigger server for evaluation before the updates are made to the
registry.
Although generally this routine it is not called directly, this
reference page is provided for users who are writing the attribute
trigger servers that will receive sec_attr_trig_update() input and
supply its output.
The sec_attr_trig_update() routine is called by the DCE attribute update
code for all schema entries that specify an update attribute trigger
(sec_attr_trig_type_update specified with the sec_attr_trig_type_flags_t
data type). The attribute update code passes the sec_attr_trig_update()
input parameters to a user-written update attribute trigger server and
receives the output parameters back from the server. The attribute
trigger server is responsible for evaluating the semantics of the entry
in order to reject or accept it, and the attribute trigger server may
even make changes in the output it sends back to the update code to
ensure the entry adheres to the semantics. The output received from
the attribute trigger server is in a form to be stored in the registry.
(Note that update attribute trigger servers do not store attribute
values. Attribute values are stored in the registry database.)
This is an atomic operation: if the update of any attribute in the
array fails to pass the evaluation, all updates are aborted. The
attribute causing the update to fail is identified in failure_index.
If the failure cannot be attributed to a given attribute, failure_index
contains -1.
For objects in the local cell, set the cell_name parameter to null, and
the component_name parameter to specify the object's name.
For objects in a foreign cell, set the cell_name parameter the the name
of the foreign cells, and the component_name parameter to specify the
UUID in string format that identifies the object in the foreign cell.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_ATTR_TRIG.IDL
The idl file from which dce/sec_attr_trig.h was derived.
ERRORS
database read only
server unavailable
invalid/unsupported attribute type
invalid encoding type
value not unique
site read only
unauthorized
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_attr_trig_query
4.26 – sec_cred_free_attr_cursor
NAME
sec_cred_free_attr_cursor - Free the local resources allocated to a
sec_attr_cursor_t used by the
sec_cred_get_extended_attrs() call
SYNOPSIS
#include <dce/sec_cred.h>
void sec_cred_free_attr_cursor (
sec_cred_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input/Output
cursor
As input, a pointer to a sec_cred_attr_cursor_t whose resources
are to be freed. As output a pointer to an initialized
sec_cred_attr_cursor_t with allocated resources freed.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_cred_free_attr_cursor() routine frees the resources assoicated
with a cursor of type sec_cred_attr_cursor_t used by the
sec_cred_get_extended_attrs() call.
ERRORS
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_extended_attrs
sec_cred_initialize_attr_cursor
4.27 – sec_cred_free_cursor
NAME
sec_cred_free_cursor - Release local resources allocated to a
sec_cred_cursor_t used by the
sec_cred_get_delegate() call
SYNOPSIS
#include <dce/sec_cred.h>
void sec_cred_free_cursor (
sec_cred_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input/Output
cursor
As input, a sec_cred_cursor_t whose resources are to be freed.
As output, a sec_cred_cursor_t whose resources are freed.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_cred_free_cursor() routine releases local resources allocated
to a sec_cred_cursor_t used by the sec_cred_get_delegate() call.
ERRORS
sec_login_s_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_initialize_cursor
4.28 – sec_cred_free_pa_handle
NAME
sec_cred_free_pa_handle - Free the local resources allocated to
a privilege attribute handle of type
sec_cred_pa_handle_t used by the
sec_cred_get_initiator() and
sec_cred_get_delegate() calls
SYNOPSIS
#include <dce/sec_cred.h>
void sec_cred_free_pa_handle (
sec_cred_pa_handle__t *pa_handle,
error_status_t *status);
PARAMETERS
Input/Output
pa_handle
As input, a pointer to a sec_cred_pa_handle_t whose resources
are to be freed. As output a pointer to a sec_cred_pa_handle_t
with allocated resources freed.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_cred_free_pa_handle() routine frees the resources assoicated
with a privilege attribute handle of type sec_cred_pa_handle_t used
by the sec_cred_get_initiator() and sec_cred_get_delegate() calls.
ERRORS
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_initiator
sec_cred_get_delegate
4.29 – sec_cred_get_authz_session_info
NAME
sec_cred_get_authz_session_info - Returns session-specific information
that represents an authenticated
client's credentials.
SYNOPSIS
#include <dce/sec_cred.h>
void sec_cred_get_authz_session_info(
rpc_authz_cred_handle_t callers_identity,
uuid_t *session_id,
sec_timeval_t *session_expiration,
error_status_t *status );
PARAMETERS
Input
callers_identity
A credential handle of type rpc_authz_cred_handle_t. This handle is
supplied as output of the rpc_binding_inq_auth_caller() call.
Output
session_ID
A pointer to a uuid_t that identifies the client's DCE authorization
session.
session_expiration
A pointer to a sec_timeval_t that specifies the expiration time of
the authenticated client's credentials.
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_cred_get_authz_session_info() routine retrieves session-specific
information that represents the credentials of authenticated client
specified by callers_identity. If the client is a member of a delegation
chain, the information represents the credentials of all members of the
chain.
The information can aid application servers in the construction of
identity-based caches. For example, it could be used as a key into a
cache of previously allocated delegation contexts and thus avoid the
overhead of allocating a new login context on every remote operation.
It could also be used as a key into a table of previously computed
authorization decisions.
Before you execute this call, you must execute an
rpc_binding_inq_auth_caller() call to obtain an rpc_authz_cred_handle_t
for the callers_identity parameter.
ERRORS
sec_cred_s_authz_cannot_comply
error_status_ok
RELATED INFORMATION
Functions: sec_intro
rpc_binding_inq_auth_caller
4.30 – sec_cred_get_client_princ_name
NAME
sec_cred_get_client_princ_name - Returns the principal name associated
with a credential handle
SYNOPSIS
#include <dce/sec_cred.h>
void sec_cred_get_client_princ_name(
rpc_authz_cred_handle_t callers_identity,
unsigned_char_p_t *client_princ_name,
error_status_t *status);
PARAMETERS
Input
callers_identity
A handle of type rpc_authz_cred_handle_t to the credentials for
which to return the principal name. This handle is supplied as
output of the rpc_binding_inq_auth_caller() call.
Output
client_princ_name
A pointer to the principal name of the server's rpc client.
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_cred_get_client_princ_name() routine extracts the principal name
associated with the credentials identified by callers_pas.
Before you execute sec_cred_get_client_princ_name(), you must execute an
rpc_binding_inq_auth_caller() call to obtain an rpc_authz_cred_handle_t
for the callers_identity parameter.
ERRORS
sec_cred_s_authz_cannot_comply
error_status_ok
RELATED INFORMATION
Functions: sec_intro
rpc_binding_inq_auth_caller
4.31 – sec_cred_get_deleg_restrictions
NAME
sec_cred_get_deleg_restrictions - Returns delegate restrictions
from a privilege attribute handle
SYNOPSIS
#include <dce/sec_cred.h>
sec_id_restriction_set_t *sec_cred_get_deleg_restrictions(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
PARAMETERS
Input
callers_pas
A value of type sec_cred_pa_handle_t that provides a handle to a
principal's privilege attributes. This handle is supplied as output
of the sec_cred_get_initiator() call, the sec_cred_get_delegate()
call and the sec_login_cred calls.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_deleg_restrictions () routine extracts delegate
restrictions from the privilege attribute handle identified by
callers_pas. The restrictions are returned in a
sec_id_restriction_set_t.
Before you execute sec_cred_get_pa_data(), you must execute a
sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
ERRORS
sec_cred_s_invalid_pa_handle
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_get_initiator
4.32 – sec_cred_get_delegate
NAME
sec_cred_get_delegate - Returns a handle to the privilege attributes
of an intermediary in a delegation chain
SYNOPSIS
#include <dce/sec_cred.h>
sec_cred_pa_handle_t sec_cred_get_delegate(
rpc_authz_cred_handle_t callers_identity,
sec_cred_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input
callers_identity
A handle of type rpc_authz_cred_handle_t. This handle is supplied
as output of the rpc_binding_inq_auth_caller() call.
Input/Output
cursor
As input, a pointer to a cursor of type sec_cred_cursor_t that has
been initialized by the sec_cred_initialize_cursor() call. As an
output parameter, cursor is a pointer to a cursor of type
sec_attr_srch_cursor_t that is positioned past the principal whose
privilege attributes have been returned in this call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_delegate() routine returns a handle to the the
privilege attributes of an intermediary in a delegation chain that
performed an authenticated RPC operation.
This call is used by servers. Clients use the
sec_login_cred_get_delegate() routine to return the privilege attribute
handle of an intermediary in a delegation chain.
The credential handle identified by callers_identity contains authenti-
cation and authorization information for all delegates in the chain.
This call returns a handle (sec_cred_pa_handle_t) to the privilege
attributes of one of the delegates in the binding handle. The
sec_cred_pa_handle_t returned by this call is used in other
sec_cred_get... calls to obtain privilege attribute information for a
single delegate.
To obtain the privilege attributes of each delegate in the credential
handle identified by callers_identity, execute this call until the
message sec_cred_s_no_more_entries is returned.
Before you execute sec_cred_get_delegate(), you must execute:
+ An rpc_binding_inq_auth_caller() call to obtain an
rpc_authz_cred_handle_t for the callers_identity parameter.
+ A sec_cred_initialize_cursor() call to initialize a cursor of type
sec_cred_cursor_t.
Use the sec_cred_free_pa_handle() all to free the resources associated
with the sec_cred_pa_handle_t.
ERRORS
sec_cred_s_invalid_auth_handle
sec_cred_s_invalid_cursor
sec_cred_s_no_more_entries
error_status_ok
RELATED INFORMATION
Functions: sec_intro
rpc_binding_inq_auth_caller
sec_cred_initialize_cursor
sec_cred_get_deleg_restrictions
sec_cred_get_delegation_type
sec_cred_get_extended_attrs
sec_cred_get_opt_restrictions
sec_cred_get_pa_date
sec_cred_get_req_restrictions
sec_cred_get_tgt_restrictions
sec_cred_get_v1_pac
sec_cred_free_pa_handle
4.33 – sec_cred_get_delegation_type
NAME
sec_cred_get_delegation_type - Returns the delegation type from a
privilege attribute handle
SYNOPSIS
#include <dce/sec_cred.h>
sec_id_delegation_type_t *sec_cred_get_delegation_type(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
PARAMETERS
Input
callers_pas
A value of type sec_cred_pa_handle_t that provides a handle to
a principal's privilege attributes. This handle is supplied as
output of either the sec_cred_get_initiator() call or
ec_cred_get_delegate() call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_delegation_type () routine extracts the delegation
type from the privilege attribute handle identified by callers_pas
and returns it in a sec_id_delegation_type_t.
Before you execute sec_cred_get_delegation_type(), you must execute a
sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
ERRORS
sec_cred_s_invalid_pa_handle
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_get_initiator
4.34 – sec_cred_get_extended_attrs
NAME
sec_cred_get_extended_attrs - Returns extended attributes from a
privilege handle
SYNOPSIS
#include <dce/sec_cred.h>
void sec_cred_get_extended_attrs(
sec_cred_pa_handle_t callers_pas,
sec_cred_attr_cursor_t *cursor
sec_attr_t *attr
error_status_t *status);
PARAMETERS
Input
callers_pas
A handle of type sec_cred_pa_handle_t to the caller's privilege
attributes. This handle is supplied as output of either the
sec_cred_get_initiator() call or sec_cred_get_delegate() call.
Input/Output
cursor
A cursor of type sec_cred_attr_cursor_t that has been initialized
by the sec_cred_initialize_attr_cursor() routine. As input cursor
must be initialized. As output, cursor is positioned at the first
attribute after the returned attribute.
Output
attr
A pointer to a value of sec_attr_t that contains extended registry
attributes.
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_extended_attrs() routine extracts extended registry
initialized from the privilege attribute handle identified by
callers_pas.
Before you execute call, you must execute:
+ A sec_cred_get_initiator() or sec_cred_get_delegate() call to
obtain a sec_cred_pa_handle_t for the callers_pas parameter.
+ A sec_cred_initialize_attr_cursor() to initialize a sec_attr_t.
To obtain all the extended registry attributes in the privilege
attribute handle, repeat sec_cred_get_extended_attrs() calls until
the status message no_more_entries_available is returned.
ERRORS
sec_cred_s_invalid_pa_handle
sec_cred_s_invalid_cursor
sec_cred_s_no_more_entries
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_initialize_attr_cursor
sec_cred_get_initiator
sec_cred_get_delegate
4.35 – sec_cred_get_initiator
NAME
sec_cred_get_initiator - Returns the privilege attributes of the
initiator of a delegation chain
SYNOPSIS
#include <dce/sec_cred.h>
sec_cred_pa_handle_t sec_cred_get_initiator(
rpc_authz_cred_handle_t callers_identity,
error_status_t *status);
PARAMETERS
Input
callers_identity
A credential handle of type rpc_authz_cred_handle_t. This handle
is supplied as output of the rpc_binding_inq_auth_caller() call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_initiator() routine returns a handle to the the
privilege attributes of the initiator of a delegation chain that
performed an authenticated RPC operation.
The credential handle identified by callers_identity contains
authentication and authorization information for all delegates in
the chain. This call returns a handle (sec_cred_pa_handle_t) to the
privilege attributes of the client that initiated the delegation chain.
The sec_cred_pa_handle_t returned by this call is used in other
sec_cred_get... calls to obtain privilege attribute information for the
initiator.
Before you execute sec_cred_get_initiator(), you must execute an
rpc_binding_inq_auth_caller() call to obtain an rpc_authz_cred_handle_t
for the callers_identity parameter.
ERRORS
sec_cred_s_invalid_auth_handle
error_status_ok
RELATED INFORMATION
Functions: sec_intro
rpc_binding_inq_auth_caller
sec_cred_get_deleg_restrictions
sec_cred_get_delegation_type
sec_cred_get_extended_attrs
sec_cred_get_opt_restrictions
sec_cred_get_pa_date
sec_cred_get_req_restrictions
sec_cred_get_tgt_restrictions
sec_cred_get_v1_pac
4.36 – sec_cred_get_opt_restrictions
NAME
sec_cred_get_opt_restrictions - Returns optional restrictions from
a privilege handle
SYNOPSIS
#include <dce/sec_cred.h>
sec_id_opt_req_t *sec_cred_get_opt_restrictions(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
PARAMETERS
Input
callers_pas
A handle of type sec_cred_pa_handle_t to a principal's privilege
attributes. This handle is supplied as output of either the
sec_cred_get_initiator() call or sec_cred_get_delegate() call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_opt_restrictions () routine extracts optional
restrictions from the privilege attribute handle identified by
callers_pas and returns them in a sec_id_restriction_set_t.
Before you execute sec_cred_get_pa_data(), you must execute a
sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
ERRORS
sec_cred_s_invalid_pa_handle
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_get_initiator
4.37 – sec_cred_get_pa_data
NAME
sec_cred_get_pa_data - Returns identity information from a privilege
attribute handle
SYNOPSIS
#include <dce/sec_cred.h>
sec_id_pa_t *sec_cred_get_pa_data(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
PARAMETERS
Input
callers_pas
A handle of type sec_cred_pa_handle_t to a principal's privilege
attributes. This handle is supplied as output of either the
sec_cred_get_initiator() call or sec_cred_get_delegate() call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_pa_data() routine extracts identity information from
the privilege attribute handle specified by callers_pas and returns it
in a sec_id_pa_t. The identity information includes an identifier of
the princpal's locall cell and the principal's local and foreign group
sets.
Before you execute sec_cred_get_pa_data(), you must execute a
sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
ERRORS
sec_cred_s_invalid_pa_handle
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_get_initiator
4.38 – sec_cred_get_req_restrictions
NAME
sec_cred_get_req_restrictions - Returns required restrictions
from a privilege attribute handle
SYNOPSIS
#include <dce/sec_cred.h>
sec_id_opt_req_t *sec_cred_get_req_restrictions (
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
PARAMETERS
Input
callers_pas
A handle of type sec_cred_pa_handle_t to a principal's privilege
attributes. This handle is supplied as output of either the
sec_cred_get_initiator() call or sec_cred_get_delegate() call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_req_restrictions() routine extracts required
restrictions from the privilege attribute handle identified by
callers_pas and returns them in a sec_id_opt_req_t.
Before you execute sec_cred_get_req_restrictions(), you must execute a
sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
ERRORS
sec_cred_s_invalid_pa_handle
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_get_initiator
4.39 – sec_cred_get_tgt_restrictions
NAME
sec_cred_get_tgt_restrictions - Returns target restrictions from a
privilege attribute handle
SYNOPSIS
#include <dce/sec_cred.h>
sec_id_restriction_set_t *sec_cred_get_tgt_restrictions(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
PARAMETERS
Input
callers_pas
A handle of type sec_cred_pa_handle_t to a principal's privilege
attributes. This handle is supplied as output of either the
sec_cred_get_initiator() call or sec_cred_get_delegate() call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_tgt_restrictions() routine extracts target
restrictions from the privilege attribute handle identified by
callers_pas and returns them in a sec_id_restriction_set_t.
Before you execute sec_cred_get_tgt_restrictions(), you must execute a
sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
ERRORS
sec_cred_s_invalid_pa_handle
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_get_initiator
4.40 – sec_cred_get_v1_pac
NAME
sec_cred_get_v1_pac - Returns pre-1.1 PAC from a privilege attribute
handle
SYNOPSIS
#include <dce/sec_cred.h>
sec_id_pac_t *sec_cred_get_v1_pac(
sec_cred_pa_handle_t callers_pas,
error_status_t *status);
PARAMETERS
Input
callers_pas
A handle of type sec_cred_pa_handle_t to the principal's privilege
attributes. This handle is supplied as output of either the
sec_cred_get_initiator() call or sec_cred_get_delegate() call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok.
DESCRIPTION
The sec_cred_get_v1_pac() routine extracts the privilege attributes
from a pre-1.1 PAC for the privilege attribute handle specified by
callers_pas and returns them in a sec_id_pa_t.
Before you execute sec_cred_get_v1_pac(), you must execute a
sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a
sec_cred_pa_handle_t for the callers_pas parameter.
ERRORS
sec_cred_s_invalid_pa_handle
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_get_initiator
4.41 – sec_cred_initialize_attr_cursor
NAME
sec_cred_initialize_attr_cursor - Initialize a sec_attr_cursor_t used
by the sec_cred_get_extended_attrs()
call
SYNOPSIS
#include <dce/sec_cred.h>
void sec_cred_initialize_attr_cursor (
sec_cred_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input/Output
cursor
As input, a pointer to a sec_cred_attr_cursor_t to be
initialized. As output a pointer to an initialized
sec_cred_attr_cursor_t.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_cred_initialize_attr_cursor() routine allocates and initializes
a cursor of type sec_cred_attr_cursor_t for use with the
sec_cred_get_extended_attrs() call. Use the sec_cred_free_attr_cursor()
call to free the resources allocated to cursor.
ERRORS
sec_login_s_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_extended_attrs
sec_cred_free_attr_cursor
4.42 – sec_cred_initialize_cursor
NAME
sec_cred_initialize_cursor - Initialize a sec_cred_cursor_t used by
the sec_cred_get_delegate() call
SYNOPSIS
#include <dce/sec_cred.h>
void sec_cred_initialize_cursor (
sec_cred_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input/Output
cursor
As input, a sec_cred_cursor_t to be initialized. As output,
an initialized sec_cred_cursor_t.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_cred_initialize_cursor() routine initializes a cursor of type
sec_cursor_t for use with the sec_cred_get_delegate() call. Use the
sec_cred_free_cursor() call to free the resources allocated to cursor.
ERRORS
sec_login_s_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_delegate
sec_cred_free_cursor
4.43 – sec_cred_is_authenticated
NAME
sec_cred_is_authenticated - Returns true if the supplied credentials
are authenticated and false if they are
not
SYNOPSIS
#include <dce/sec_cred.h>
boolean32 sec_cred_is_authenticated(
rpc_authz_cred_handle_t callers_identity,
error_status_t *status);
PARAMETERS
Input
callers_identity
A handle of type rpc_authz_cred_handle_t to the credentials to
check for authentication. This handle is supplied as output of
the rpc_binding_inq_auth_caller() call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_cred_is_authenticated() routine returns true if the credentials
identified by callers_identity are authenticated or false if they are
not.
Before you execute this call, you must execute an
rpc_binding_inq_auth_caller() call to obtain an rpc_authz_cred_handle_t
for the callers_identity parameter.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_CRED.IDL
The idl file from which dce/sec_cred.h was derived.
RETURN VALUES
The routine returns true is the credentials are authenticated; false if
they are not.
ERRORS
TBS
RELATED INFORMATION
Functions: sec_intro
rpc_binding_inq_auth_caller
4.44 – sec_id_gen_group
NAME
sec_id_gen_group - Generates a global name from cell and group UUIDs
SYNOPSIS
#include <dce/secidmap.h>
void sec_id_gen_group(
sec_rgy_handle_t context,
uuid_t *cell_idp,
uuid_t *group_idp,
sec_rgy_name_t global_name,
sec_rgy_name_t cell_namep,
sec_rgy_name_t group_namep,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
cell_idp
A pointer to the UUID of the home cell of the group whose name is
in question.
group_idp
A pointer to the UUID of the group whose name is in question.
Output
global_name
The global (full) name of the group in sec_rgy_name_t form.
cell_namep
The name of the group's home cell in sec_rgy_name_t form.
group_namep
The local (with respect to the home cell) name of the group in
sec_rgy_name_t form.
status
A pointer to the completion status. On successful completion, the
function returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_id_gen_group() routine generates a global name from input cell
and group UUIDs. For example, given a UUID specifying the
cell /.../world/hp/brazil, and a UUID specifying a group resident in
that cell named writers, the routine would return the global name of
that group, in this case, /.../world/hp/brazil/writers. It also returns
the simple names of the cell and group, translated from the UUIDs.
The routine will not produce translations to any name for which a NULL
pointer has been supplied.
FILES
SYS$COMMON:[DCE$LIBRARY]SECIDMAP.IDL
The idl file from which dce/secidmap.h was derived.
ERRORS
sec_id_e_name_too_long
The name is too long for current implementation.
sec_id_e_bad_cell_uuid
The cell UUID is not valid.
sec_rgy_object_not_found
The registry server could not find the specified group.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_id_gen_name
sec_id_parse_group
sec_id_parse_name
4.45 – sec_id_gen_name
NAME
sec_id_gen_name - Generates a global name from cell and principal
UUIDs
SYNOPSIS
#include <dce/secidmap.h>
void sec_id_gen_name(
sec_rgy_handle_t context,
uuid_t *cell_idp,
uuid_t *princ_idp,
sec_rgy_name_t global_name,
sec_rgy_name_t cell_namep,
sec_rgy_name_t princ_namep,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
cell_idp
A pointer to the UUID of the home cell of the principal whose
name is in question.
princ_idp
A pointer to the UUID of the principal whose name is in question.
Output
global_name
The global (full) name of the principal in sec_rgy_name_t form.
cell_namep
The name of the principal's home cell in sec_rgy_name_t form.
princ_namep
The local (with respect to the home cell) name of the principal in
sec_rgy_name_t form.
status
A pointer to the completion status. On successful completion, the
function returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_id_gen_name() routine generates a global name from input cell
and principal UUIDs. For example, given a UUID specifying the
cell /.../world/hp/brazil, and a UUID specifying a principal resident
in that cell named writers/tom, the routine would return the global name
of that principal, in this case, /.../world/hp/brazil/writers/tom. It
also returns the simple names of the cell and principal, translated from
the UUIDs.
The routine will not produce translations to any name for which a NULL
pointer has been supplied.
Permissions Required
The sec_id_gen_name() routine requires at least one permission of any
kind on the account associated with the input cell and principal UUIDs.
FILES
SYS$COMMON:[DCE$LIBRARY]SECIDMAP.IDL
The idl file from which dce/secidmap.h was derived.
ERRORS
sec_id_e_name_too_long
The name is too long for current implementation.
sec_id_e_bad_cell_uuid
The cell UUID is not valid.
sec_rgy_object_not_found
The registry server could not find the specified principal.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_id_gen_group
sec_id_parse_group
sec_id_parse_name
4.46 – sec_id_parse_group
NAME
sec_id_parse_group - Translates a global name into group and cell
names and UUIDs
SYNOPSIS
#include <dce/secidmap.h>
void sec_id_parse_group(
sec_rgy_handle_t context,
sec_rgy_name_t global_name,
sec_rgy_name_t cell_namep,
uuid_t *cell_idp,
sec_rgy_name_t group_namep,
uuid_t *group_idp,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
global_name
The global (full) name of the group in sec_rgy_name_t form.
Output
cell_namep
The output name of the group's home cell in sec_rgy_name_t form.
cell_idp
A pointer to the UUID of the home cell of the group whose name
is in question.
group_namep
The local (with respect to the home cell) name of the group in
sec_rgy_name_t form.
group_idp
A pointer to the UUID of the group whose name is in question.
status
A pointer to the completion status. On successful completion, the
function returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_id_parse_group() routine translates a global group name into
a cell name and a cell-relative group name. It also returns the UUIDs
associated with the group and its home cell.
The routine will not produce translations to any name for which a NULL
pointer has been supplied.
FILES
SYS$COMMON:[DCE$LIBRARY]SECIDMAP.IDL
The idl file from which dce/secidmap.h was derived.
ERRORS
sec_id_e_name_too_long
The name is too long for current implementation.
sec_id_e_bad_cell_uuid
The cell UUID is not valid.
sec_rgy_object_not_found
The registry server could not find the specified group.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_id_gen_group
sec_id_gen_name
sec_id_parse_group
sec_id_parse_name
4.47 – sec_id_parse_name
NAME
sec_id_parse_name - Translates a global name into principal and
cell names and UUIDs
SYNOPSIS
#include <dce/secidmap.h>
void sec_id_parse_name(
sec_rgy_handle_t context,
sec_rgy_name_t global_name,
sec_rgy_name_t cell_namep,
uuid_t *cell_idp,
sec_rgy_name_t princ_namep,
uuid_t *princ_idp,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
global_name
The global (full) name of the principal in sec_rgy_name_t form.
Output
cell_namep
The output name of the principal's home cell in sec_rgy_name_t
form.
cell_idp
A pointer to the UUID of the home cell of the principal whose name
is in question.
princ_namep
The local (with respect to the home cell) name of the principal
in sec_rgy_name_t form.
princ_idp
A pointer to the UUID of the principal whose name is in question.
status
A pointer to the completion status. On successful completion, the
function returns error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_id_parse_name() routine translates a global principal name into
a cell name and a cell-relative principal name. It also returns the
UUIDs associated with the principal and its home cell.
The routine will not produce translations to any name for which a NULL
pointer has been supplied.
Permissions Required
Only if princ_idp is requested as output does the sec_id_parse_name()
routine require a permission. In this case, the routine requires at
least one permission of any kind on the account whose global principal
name is to be translated.
FILES
SYS$COMMON:[DCE$LIBRARY]SECIDMAP.IDL
The idl file from which dce/secidmap.h was derived.
ERRORS
sec_id_e_name_too_long
The name is too long for current implementation.
sec_id_e_bad_cell_uuid
The cell UUID is not valid.
sec_rgy_object_not_found
The registry server could not find the specified principal.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_id_gen_name
4.48 – sec_key_mgmt_change_key
NAME
sec_key_mgmt_change_key - Changes a principal's key
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_change_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
unsigned32 key_vno,
void *keydata,
sec_timeval_period_t *garbage_collect_time,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine.
A value of NULL specifies that the default key file
(DCE$LOCAL:[KRB]V5SRVTAB.;) should be used. A key file name
specifies that file should be used as the key file. You must
prepend the file's absolute filename with FILE: and the file
must have been created with the rgy_edit ktadd command or the
sec_key_mgmt_set_key function.
Any other value specifies an argument for the get_key_fn key
acquisition routine. See the rpc_server_register_auth_info
reference page for more information.
principal_name
A pointer to a character string indicating the name of the
principal whose key is to be changed.
key_vno
The version number of the new key. If 0 (zero) is specified,
the routine will select the next appropriate key version number.
keydata
A pointer to a structure of type sec_passwd_rec_t.
Output
garbage_collect_time
The number of seconds that must elapse before all currently
valid tickets (which are encoded with the current or previous
keys) expire. At that time, all obsolete keys may be "garbage
collected", since no valid tickets encoded with those keys will
remain outstanding on the network.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_change_key() routine performs all activities necessary
to update a principal's key to the specified value. This includes
updating any local storage for the principal's key and also performing
any remote operations needed to keep the authentication protocol (or
network registry) current. Old keys for the principal are garbage
collected if appropriate.
FILES
The idl file from which dce/keymgmt.h was derived.
ERRORS
Any error condition will leave the key state unchanged.
sec_key_mgmt_e_key_unavailable
The old key is not present and therefore cannot be used
to set a client side authentication context.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_auth_unavailable
The authentication protocol is not available to update
the network database or to obtain the necessary network
credentials.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
sec_key_mgmt_e_key_unsupported
The key type is not supported.
sec_key_mgmt_e_key_version_ex
A key with this version number already exists.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
sec_rgy_object_not_found
No principal was found with the given name.
sec_login_s_no_memory
A memory allocation error occurred.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_generate_key
sec_key_mgmt_set_key
4.49 – sec_key_mgmt_delete_key
NAME
sec_key_mgmt_delete_key - Deletes a key from the local storage
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_delete_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
unsigned32 key_vno,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine.
A value of NULL specifies that the default key file
(DCE$LOCAL:[KRB]V5SRVTAB.;) should be used. A key file name
specifies that file should be used as the key file. You must
prepend the file's absolute filename with FILE: and the file
must have been created with the rgy_edit ktadd command or the
sec_key_mgmt_set_key function. Any other value specifies an
argument for the get_key_fn key acquisition routine. See the
rpc_server_register_auth_info() reference page for more
information.
principal_name
A pointer to a character string indicating the name of the
principal whose key is to be deleted.
key_vno
The version number of the desired key.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_delete_key() routine deletes the specified key from
the local key store. If an administrator ever discovers or suspects that
the security of a server's key has been compromised, the administrator
should delete the key immediately with sec_key_mgmt_delete_key(). This
routine removes the key from the local key storage, which invalidates
all extant tickets encoded with the key. If the compromised key is the
current one, the principal should change the key with
sec_key_mgmt_change_key() before deleting it. It is not an error for a
process to delete the current key (as long as it is done after the
network context has been established), but it may seriously
inconvenience legitimate clients of a service.
This routine deletes all key types that have the specified key version
number. A key type identifies the data encryption algorithm being used
(for example, DES). This routine differs from
sec_key_mgmt_delete_key_type() in that sec_key_mgmt_delete_key_type()
deletes only the specified key version of the specified key type from
the local key store.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
Any error condition will leave the key state unchanged.
sec_key_mgmt_e_key_unavailable
The requested key is not present.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_delete_key_type
sec_key_mgmt_garbage_collect
4.50 – sec_key_mgmt_delete_key_type
NAME
sec_key_mgmt_delete_key_type - Deletes a key version of a key
type from the local key storage
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_delete_key_type(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
void *keytype,
unsigned32 key_vno,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine. A value of NULL
specifies that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;)
should be used. A key file name specifies that file should be
used as the key file. You must prepend the file's absolute
filename with FILE: and the file must have been created with
the rgy_edit ktadd command or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the get_key_fn key
acquisition routine. See the rpc_server_register_auth_info()
reference page for more information.
principal_name
A pointer to a character string indicating the name of the
principal whose key type is to be deleted.
keytype
A pointer to a value of type sec_passwd_type_t. The value
identifies the data encryption algorithm that is being used
(for example, DES).
key_vno
The version number of the desired key.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_delete_key_type() routine deletes the specified key
version of the specified key type from the local key store. It differs
from sec_key_mgmt_delete_key() in that sec_key_mgmt_delete_key()
deletes all key types that have the same key version number.
This routine removes the key from the local key storage, which
invalidates all extant tickets encoded with the key. If the key in
question is the current one, the principal should change the key with
sec_key_mgmt_change_key() before deleting it. It is not an error for
a process to delete the current key (as long as it is done after the
network context has been established), but it may seriously
inconvenience legitimate clients of a service.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
Any error condition will leave the key state unchanged.
sec_key_mgmt_e_key_unavailable
The requested key is not present.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_delete_key
sec_key_mgmt_garbage_collect
4.51 – sec_key_mgmt_free_key
NAME
sec_key_mgmt_free_key - Frees the memory used by a key value
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_free_key(
void *keydata,
error_status_t *status);
PARAMETERS
Input
keydata
A pointer to a structure of type sec_passwd_rec_t.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok.
DESCRIPTION
The sec_key_mgmt_free_key() routine releases any storage allocated for
the indicated key data by sec_key_mgmt_get_key(). The storage for the
key data returned by sec_key_mgmt_get_key() is dynamically allocated.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_get_key
4.52 – sec_key_mgmt_garbage_collect
NAME
sec_key_mgmt_garbage_collect - Deletes obsolete keys
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_garbage_collect(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine. A value of NULL
specifies that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;)
should be used. A key file name specifies that file should be
used as the key file. You must prepend the file's absolute
filename with FILE: and the file must have been created with
the rgy_edit ktadd command or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the get_key_fn key
acquisition routine. See the rpc_server_register_auth_info()
reference page for more information.
principal_name
A pointer to a character string indicating the name of the
principal whose key information is to be garbage collected.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_garbage_collect() routine discards any obsolete key
information for this principal. An obsolete key is one that can only
decode invalid tickets. As an example, consider a key that was in use
on Monday, and was only used to encode tickets whose maximum lifetime
was 1 day. If that key was changed at 8:00 a.m. Tuesday morning, then
it would become obsolete by 8:00 a.m. Wednesday morning, at which time
there could be no valid tickets outstanding.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
Requested key not present.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
sec_rgy_object_not_found
No principal was found with the given name.
sec_login_s_no_memory
A memory allocation error occurred.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_delete_key
4.53 – sec_key_mgmt_gen_rand_key
NAME
sec_key_mgmt_gen_rand_key - Generates a new random key of a specified
key type
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_gen_rand_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
void *keytype,
unsigned32 key_vno,
void **keydata,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine. A value of NULL
specifies that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;)
should be used. A key file name specifies that file should be
used as the key file. You must prepend the file's absolute
filename with FILE: and the file must have been created with
the rgy_edit ktadd command or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the get_key_fn key
acquisition routine. See the rpc_server_register_auth_info()
reference page for more information.
principal_name
A pointer to a character string indicating the name of the
principal for whom the key is to be generated.
keytype
A pointer to a value of type sec_passwd_type_t. The value
identifies the data encryption algorithm to be used for the key
(for example, DES).
key_vno
The version number of the new key.
Output
keydata
A pointer to a value of sec_passwd_rec_t. The storage for keydata
is allocated dynamically, so the returned pointer actually
indicates a pointer to the key value. The storage for this data
may be freed with the sec_key_mgmt_free_key() function.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_gen_rand_key() routine generates a new random key
for a specified principal and of a specified key type. The generated
key can be used with the sec_key_mgmt_change_key() and
sec_key_mgmt_set_key() routines.
Note that to initialize the random keyseed, the process must first
make an authenticated call such as sec_rgy_site_open().
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_key_mgmt_e_not_implemented
The specified keytype is not supported.
sec_s_no_key_seed
No random key seed has been set.
sec_s_no_memory
Unable to allocate memory.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_change_key
sec_key_mgmt_generate_key
sec_key_mgmt_set_key
4.54 – sec_key_mgmt_get_key
NAME
sec_key_mgmt_get_key - Retrieves a key from local storage
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_get_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
unsigned32 key_vno,
void **keydata,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine. A value of NULL specifies
that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be
used. A key file name specifies that file should be used as the
key file. You must prepend the file's absolute filename with
FILE: and the file must have been created with the rgy_edit ktadd
command or the sec_key_mgmt_set_key routine. Any other value
specifies an argument for the get_key_fn key acquisition routine.
See the rpc_server_register_auth_info() reference page for more
information.
principal_name
A pointer to a character string indicating the name of the
principal to whom the key belongs.
key_vno
The version number of the desired key. To return the latest
version of the key, set this parameter to sec_c_key_version_none.
Output
keydata
A pointer to a value of type sec_passwd_rec_t. The storage for
keydata is allocated dynamically, so the returned pointer
actually indicates a pointer to the key value. The storage for
this data may be freed with the sec_key_mgmt_free_key() routine.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_get_key() routine extracts the specified key from
the local key store.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_key_mgmt_e_key_unavailable
The requested key is not present.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
sec_s_no_memory
Unable to allocate memory.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
4.55 – sec_key_mgmt_get_next_key
NAME
sec_key_mgmt_get_next_key - Retrieves successive keys from the local
key storage
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_get_next_key(
void *cursor,
idl_char **principal_name,
unsigned32 *key_vno,
void **keydata,
error_status_t *status);
PARAMETERS
Input
cursor
A pointer to the current cursor position in the local key
storage. The cursor position is set via the routine
sec_key_mgmt_initialize_cursor().
Output
principal_name
A pointer to a character string indicating the name of the
principal associated with the extracted key. Free the storage
for the principal name with the free() function.
key_vno
The version number of the extracted key.
keydata
A pointer to a value of type sec_passwd_rec_t. The storage for
keydata is allocated dynamically, so the returned pointer
actually indicates a pointer to the key value. The storage for
this data may be freed with the sec_key_mgmt_free_key() function.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_get_next_key() routine extracts the key pointed to by
the cursor in the local key store and updates the cursor to point to the
next key. By repeatedly calling this routine you can scan all the keys
in the local store.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_key_mgmt_e_key_unavailable
The requested key is not present.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
sec_s_no_memory
Unable to allocate memory.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_get_key
sec_key_mgmt_initialize_cursor
4.56 – sec_key_mgmt_get_next_kvno
NAME
sec_key_mgmt_get_next_kvno - Retrieves the next eligible key version
number for a key
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_get_next_kvno(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
void *keytype,
unsigned32 *key_vno,
unsigned32 *next_key_vno,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine. A value of NULL specifies
that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be
used. A key file name specifies that file should be used as the
key file. You must prepend the file's absolute filename with
FILE: and the file must have been created with the rgy_edit ktadd
command or the sec_key_mgmt_set_key routine. Any other value
specifies an argument for the get_key_fn key acquisition routine.
See the rpc_server_register_auth_info() reference page for more
information.
principal_name
A pointer to a character string indicating the name of the
principal associated with the key.
keytype
A pointer to a value of type sec_passwd_type_t. The value
identifies the data encryption algorithm (for example, DES)
being used for the key.
Output
key_vno
The current version number of the key. Specify NULL if you do
not need this value to be returned.
next_key_vno
The next eligible version number for the key. Specify NULL if
you do not need this value to be returned.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_get_next_kvno() routine returns the current and next
eligible version numbers for a key from the registry server (not from
the local key table). The key is identified via its associated
authentication protocol, principal name, and key type. The arg value
associated with the key is also specified.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_key_mgmt_e_key_unavailable
The requested key is not present.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
sec_rgy_object_not_found
No principal was found with the given name.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
4.57 – sec_key_mgmt_initialize_cursor
NAME
sec_key_mgmt_initialize_cursor - Repositions the cursor in the local
key store
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_initialize_cursor(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
void *keytype,
void **cursor,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine. A value of NULL specifies
that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be
used. A key file name specifies that file should be used as the
key file. You must prepend the file's absolute filename with
FILE: and the file must have been created with the rgy_edit ktadd
command or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the get_key_fn key
acquisition routine. See the rpc_server_register_auth_info()
reference page for more information.
principal_name
A pointer to a character string indicating the name of the
principal whose key is to be accessed. To access all keys in
the local key store, supply NULL for this parameter.
keytype
A pointer to the data encryption algorithm (for example, DES)
being used for the key.
Output
cursor
The returned cursor value. The storage for the cursor information
is allocated dynamically, so the returned pointer actually
indicates a pointer to the cursor value. The storage for this
data may be freed with the sec_key_mgmt_release_cursor() routine.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_initialize_cursor() routine resets the cursor in the
local key store.
Use this routine to reposition the cursor before performing a scan of
the local store via sec_key_mgmt_get_next_key(). The returned cursor
value is supplied as input to sec_key_mgmt_get_next_key().
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_s_no_memory
Unable to allocate memory.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_get_next_key
sec_key_mgmt_release_cursor
4.58 – sec_key_mgmt_manage_key
NAME
sec_key_mgmt_manage_key - Automatically changes a principal's key
before it expires
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_manage_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine. A value of NULL specifies
that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be
used. A key file name specifies that file should be used as the
key file. You must prepend the file's absolute filename with
FILE: and the file must have been created with the rgy_edit ktadd
command or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the get_key_fn key
acquisition routine. See the rpc_server_register_auth_info()
reference page for more information.
principal_name
A pointer to a character string indicating the name of the
principal whose key is to be managed.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_manage_key() routine changes the specified principal's
key on a regular basis, as determined by the local cell's policy. It
will run indefinitely, never returning during normal operation, and
therefore should be invoked only from a thread that has been devoted to
managing keys.
This routine queries the DCE Registry to determine the password
expiration policy that applies to the named principal. It then idles
until a short time before the current key is due to expire and then uses
the sec_key_mgmt_gen_rand_key() to produce a new random key, updating
both the local key store and the DCE Registry. This routine also
invokes sec_key_mgmt_garbage_collect() as needed.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_key_mgmt_e_key_unavailable
The old key is not present and therefore cannot be used to
set a client side authentication context.
sec_key_mgmt_e_key_unsupported
The key type is not supported.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
sec_rgy_object_not_found
No principal was found with the given name.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_gen_rand_key
sec_key_mgmt_garbage_collect
4.59 – sec_key_mgmt_release_cursor
NAME
sec_key_mgmt_release_cursor - Releases the memory used by an
initialized cursor value
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_release_cursor(
void **cursor,
error_status_t *status);
PARAMETERS
Input
cursor
A pointer to the cursor value for which the storage is to be
released.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok.
DESCRIPTION
The sec_key_mgmt_release_cursor() routine releases any storage
allocated for the indicated cursor value by
sec_key_mgmt_initialize_cursor(). The storage for the cursor value
returned by sec_key_mgmt_initialize_cursor() is dynamically allocated.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_initialize_cursor
4.60 – sec_key_mgmt_set_key
NAME
sec_key_mgmt_set_key - Inserts a key value into the local storage
SYNOPSIS
#include <dce/keymgmt.h>
void sec_key_mgmt_set_key(
sec_key_mgmt_authn_service authn_service,
void *arg,
idl_char *principal_name,
unsigned32 key_vno,
void *keydata,
error_status_t *status);
PARAMETERS
Input
authn_service
Identifies the authentication protocol using this key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local key file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine. A value of NULL specifies
that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be
used. A key file name specifies that file should be used as the
key file. The file name must begin with FILE:. If the file name
does not begin with FILE:, the code will add it. Any other value
specifies an argument for the get_key_fn key acquisition routine.
See the rpc_server_register_auth_info() reference page for more
information.
principal_name
A pointer to a character string indicating the name of the
principal associated with the key to be set.
key_vno
The version number of the key to be set.
keydata
A pointer to the key value to be set.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_key_mgmt_set_key() routine performs all local activities
necessary to update a principal's key to the specified value. This
routine will not update the authentication protocol's value for the
principal's key.
In some circumstances, a server may only wish to change its key in the
local key storage, and not in the DCE Registry. For example, a
database system may have several replicas of a master database, managed
by servers running on independent machines. Since these servers together
represent only one service, they should all share the same key. This
way, a user with a ticket to use the database can choose whichever
server is least busy. To change the database key, the master server
would signal all the replica (slave) servers to change the current key
in their local key storage. They would use the sec_key_mgmt_set_key()
routine, which does not communicate with the DCE Registry. Once all the
slaves have complied, the master server can then change the Registry key
and its own local storage.
FILES
SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
The idl file from which dce/keymgmt.h was derived.
ERRORS
sec_key_mgmt_e_key_unavailable
The old key is not present and therefore cannot be used to
set a client side authentication context.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
sec_key_mgmt_e_key_unsupported
The key type is not supported.
sec_key_mgmt_e_key_version_ex
A key with this version number already exists.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_key_mgmt_change_key
sec_key_mgmt_gen_rand_key
4.61 – sec_login_become_delegate
NAME
sec_login_become_delegate - Causes an intermediate server to become a
delegate in traced delegation chain
SYNOPSIS
#include <dce/sec_login.h>
sec_login_handle_t sec_login_become_delegate(
rpc_authz_cred_handle_t callers_identity,
sec_login_handle_t my_login_context,
sec_id_delegation_type_t delegation_type_permitted,
sec_id_restriction_set_t *delegate_restrictions,
sec_id_restriction_set_t *target_restrictions,
sec_id_opt_req_t *optional_restrictions,
sec_id_opt_req_t *required_restrictions,
sec_id_compatibility_mode_t compatibility_mode,
error_status_t *status);
PARAMETERS
Input
callers_identity
A handle of type rpc_authz_cred_handle_t to the authenticated
identity of the previous delegate in the delegation chain. The
handle is supplied by the rpc_binding_inq_auth_caller() call.
my_login_context
A value of sec_login_handle_t that provides an opaque handle to
the identity of the client that is becoming the intermediate
delegate. The sec_login_handle_t that specifies the client's
identity is supplied as output of the following calls:
+ sec_login_get_current_context() if the client inherited the
identity of the current context
+ The sec_login_setup_identity() and the
sec_login_validate_identity() pair that together establish
an authenticated identity if a new identity was established
Note that this identity specified by sec_login_handle_t must be a simple
login context; it cannot be a compound identity created by a previous
sec_login_become_delegate() call.
delegation_type_permitted
A value of sec_id_delegation_type_t that specifies the type of
delegation to be enabled. The types available are:
sec_id_deleg_type_none
No delegation.
sec_id_deleg_type_traced
Traced delegation.
sec_id_deleg_type_impersonation
Simple (impersonation) delegation.
Note that the initiating client sets the type of delegation. If it is
set as traced, all delegates must also specify traced delegation; they
cannot specify simple delegation. The same is true if the initiating
client sets the delegation type as simple; all subsequent delegates must
also specify simple delegation. The intermediate delegates can,
however, specify no delegation to indicate that the delegation chain
can proceed no further.
delegate_restrictions
A pointer to a sec_id_restriction_set_t that supplies a list of
servers that can act as delegates for the intermediate client
identified by my_login_context. These servers are added to
delegates permitted by the delegate_restrictions parameter of the
sec_login_become_initiator call.
target_restrictions
A pointer to a sec_id_restriction_set_t that supplies a list of
servers that can act as targets for the intermediate client
identified by my_login_context. These servers are added to
targets specified by the target_restrictions parameter of the
sec_login_become_initiator call.
optional_restrictions
A pointer to a sec_id_opt_req_t that supplies a list of
application-defined optional restrictions that apply to the
intermediate client identified by my_login_context. These
restrictions are added to the restrictions identified by the
optional_restrictions parameter of the sec_login_become_initiator
call.
required_restrictions
A pointer to a sec_id_opt_req_t that supplies a list of
application-defined required restrictions that apply to the
intermediate client identified by my_login_context. These
restrictions are added to the restrictions identified
required_restrictions parameter of the sec_login_become_initiator
call.
compatibility_mode
A value of sec_id_compatibility_mode_t that specifies the
compatibility mode to be used when the intermediate client
operates on pre-1.1 servers. The modes available are:
sec_id_compat_mode_none
Compatibility mode is off.
sec_id_compat_mode_initiator
Compatibility mode is on. The pre-1.1 PAC data is
extracted from the EPAC of the initiating client.
sec_id_compat_mode_caller
Compatibility mode is on. The pre-1.1 PAC data
extracted from the EPAC of the last client in the
delegation chain.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_become_delegate() is used by intermediate servers to
become a delegate for the client identified by callers_identity. The
routine returns a new login context (of type sec_login_handle_t) that
carries delegation information. This information includes the delegation
type, delegate and target restrictions, and any application-defined
optional and required restrictions.
The new login context created by this call can then used to to set up
authenticated rpc with an intermediate or target server using the
rpc_binding_set_auth_info() call.
Any delegate, target, required, or optional restrictions specified in
this call are added to the restrictions specified by the initiating
client and any intermediate clients.
The sec_login_become_delegate() call is run only if the initiating
client enabled traced delegation by setting the
delegation_type_permitted parameter in the sec_login_become_initiator
call to sec_id_deleg_type_traced.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_invalid_context
sec_login_s_compound_delegate
sec_login_s_invalid_deleg_type
err_sec_login_invalid_delegate_restriction
err_sec_login_invalid_target_restriction
err_sec_login_invalid_opt_restriction
err_sec_login_invalid_req_restriction
sec_login_s_invalid_compat_mode
sec_login_s_deleg_not_enabled
error_status_ok
RELATED INFORMATION
Functions: intro
sec_login_become_initiator
sec_login_become_impersonator
rpc_binding_inq_auth_caller
sec_login_get_current_context
sec_login_setup_identity
sec_login_validate_identity
4.62 – sec_login_become_impersonator
NAME
sec_login_become_impersonator - Causes an intermediate server to
become a delegate in a simple
delegation chain
SYNOPSIS
#include <dce/sec_login.h>
sec_login_handle_t sec_login_become_impersonator(
rpc_authz_cred_handle_t callers_identity,
sec_id_delegation_type_t delegation_type_permitted,
sec_id_restriction_set_t *delegate_restrictions,
sec_id_restriction_set_t *target_restrictions,
sec_id_opt_req_t *optional_restrictions,
sec_id_opt_req_t *required_restrictions,
error_status_t *status);
PARAMETERS
Input
callers_identity
A handle of type rpc_authz_cred_handle_t to the authenticated
identity of the previous delegate in the delegation chain. The
handle is supplied by the rpc_binding_inq_auth_caller() call.
delegation_type_permitted
A value of sec_id_delegation_type_t that specifies the type of
delegation to be enabled. The types available are:
sec_id_deleg_type_none
No delegation.
sec_id_deleg_type_traced
Traced delegation.
sec_id_deleg_type_impersonation
Simple (impersonation) delegation.
The initiating client sets the type of delegation. If it is set as
traced, all delegates must also specify traced delegation; they cannot
specify simple delegation. The same is true if the initiating client
sets the delegation type as simple; all subsequent delegates must also
specify simple delegation. The intermediate delegates can, however,
specify no delegation to indicate that the delegation chain can proceed
no further.
delegate_restrictions
A pointer to a sec_id_restriction_set_t that supplies a list of
servers that can act as delegates for the client becoming the
delegate. These servers are added to the delegates permitted by
the delegate_restrictions parameter of the
sec_login_become_initiator call.
target_restrictions
A pointer to a sec_id_restriction_set_t that supplies a list of
servers that can act as targets for the client becoming the
delegate. These servers are added to targets specified by the
target_restrictions parameter of the sec_login_become_initiator
call.
optional_restrictions
A pointer to a sec_id_opt_req_t that supplies a list of
application-defined optional restrictions that apply to the
client becoming the delegate. These restrictions are added to
the restrictions identified by the optional_restrictions
parameter of the sec_login_become_initiator call.
required_restrictions
A pointer to a sec_id_opt_req_t that supplies a list of
application-defined required restrictions that apply to the
client becoming the delegate. These restrictions are added to
the restrictions identified required_restrictions parameter of
the sec_login_become_initiator call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_become_impersonator() is used by intermediate servers to
become a delegate for the client identified by callers_identity. The
routine returns a new login context (of type sec_login_handle_t) that
carries delegation information. This information includes the delegation
type, delegate, and target restrictions, and any application-defined
optional and required restrictions.
The new login context created by this call can then used to to set up
authenticated rpc with an intermediate or target server using the
rpc_binding_set_auth_info() call.
The effective optional and required restrictions are the union of the
optional and required restrictions specified in this call and specified
by the initiating client and any intermediate clients. The effective
target and delegate restrictions are the intersection of the target
and delegate restrictions specified in this call and specified by the
initiating client and any intermediate clients.
The sec_login_become_impersonator call is call is run only if the
initiating client enabled simple delegation by setting the
delegation_type_permitted parameter in the sec_login_become_initiator
call to sec_id_deleg_type_simple.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_invalid_deleg_type
err_sec_login_invalid_delegate_restriction
err_sec_login_invalid_target_restriction
err_sec_login_invalid_opt_restriction
err_sec_login_invalid_req_restriction
sec_login_s_invalid_compat_mode
sec_login_s_deleg_not_enabled
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_login_become_initiator
rpc_binding_inq_auth_caller
4.63 – sec_login_become_initiator
NAME
sec_login_become_initiator - Constructs a new login context that
enables delegation for the calling client
SYNOPSIS
#include <dce/sec_login.h>
sec_login_handle_t sec_login_become_initiator(
sec_login_handle_t my_login_context,
sec_id_delegation_type_t delegation_type_permitted,
sec_id_restriction_set_t *delegate_restrictions,
sec_id_restriction_set_t *target_restrictions,
sec_id_opt_req_t *optional_restrictions,
sec_id_opt_req_t *required_restrictions,
sec_id_compatibility_mode_t compatibility_mode,
error_status_t *status);
PARAMETERS
Input
my_login_context
A value of sec_login_handle_t that provides an opaque handle to
the identity of the client that is enabling delegation. The
sec_login_handle_t that specifies the client's identity is
supplied as output of the following calls:
+ sec_login_get_current_context() if the client inherited the
identity of the current context
+ The sec_login_setup_identity() and the
sec_login_validate_identity() pair that together establish
an authentiated identity if a new identity was established
delegation_type_permitted
A value of sec_id_delegation_type_t that specifies the type of
delegation to be enabled. The types available are:
sec_id_deleg_type_none
No delegation.
sec_id_deleg_type_traced
Traced delegation.
sec_id_deleg_type_impersonation
Simple (impersonation) delegation.
Note each subsequent intermediate delegate of the delegation chain
started by the initiating client must set the delegation type to traced
if the initiating client set it to traced or to simple if the
initiating client set it to simple. Intermediate delegates, however,
can set the delegation type to no delegation to indicate that the
delegation chain can proceed no further.
delegate_restrictions
A pointer to a sec_id_restriction_set_t that supplies a list
of servers that can act as delegates for the client initiating
delegation.
target_restrictions
A pointer to a sec_id_restriction_set_t that supplies a list
of servers that can act as targets for the client initiating
delegation.
optional_restrictions
A pointer to a sec_id_opt_req_t that supplies a list of
application-defined optional restrictions that apply to the
client initiating delegation.
required_restrictions
A pointer to a sec_id_opt_req_t that supplies a list of
application-defined required restrictions that apply to the
client initiating delegation.
compatibility_mode
A value of sec_id_compatibility_mode_t that specifies the
compatibility mode to be used when the initiating client
interacts with pre-1.1 servers. The modes available are:
sec_id_compat_mode_none
Compatibility mode is off.
sec_id_compat_mode_initiator
Compatibility mode is on. The pre-1.1 PAC data is
extracted from the EPAC of the initiating client.
sec_id_compat_mode_caller
Compatibility mode is on. The pre-1.1 PAC data
extracted from the EPAC of the last client in the
delegation chain.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_become_initiator() enables delegation for the calling
client by constructing a new login context (in a sec_login_handle_t)
that carries delegation information. This information includes the
delegation type, delegate, and target restrictions, and any
application-defined optional and required restrictions.
The new login context is then used to to set up authenticated rpc with
an intermediate server using the rpc_binding_set_auth_info() call. The
intermediary can continue the delegation chain by calling
sec_login_become_delegate (if the delegation type is
sec_id_deleg_type_traced) or sec_login_become_impersonator (if the
delegation type is sec_id_deleg_type_impersonation).
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_invalid_context
sec_login_s_invalid_deleg_type
err_sec_login_invalid_delegate_restriction
err_sec_login_invalid_target_restriction
err_sec_login_invalid_opt_restriction
err_sec_login_invalid_req_restriction
sec_login_s_invalid_compat_mode
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_login_become_delegate
sec_login_become_impersonator
sec_login_get_current_context
sec_login_setup_identity
sec_login_validate_identity
4.64 – sec_login_certify_identity
NAME
sec_login_certify_identity - Certifies the network
authentication service
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_certify_identity(
sec_login_handle_t login_context,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and UUID,
account restrictions, records of group membership, and the
process home directory. (See sec_intro for more details about
the login context.)
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_certify_identity() routine certifies that the Security
Server used to set up and validate a login context is legitimate. A
legitimate server is one that knows the host machine's secret key.
On some systems, this may be a privileged operation.
Information may be retrieved via sec_login_get_pwent(),
sec_login_get_groups(), and sec_login_get_expiration() from an
uncertified login context, but such information cannot be trusted.
All system login programs that use the sec_login interface must call
sec_login_certify_identity() to certify the Security Server. If they
do not, they open the local file system to attacks by imposter Security
servers returning suspect local process credentials (UUID and group
IDs). This operation updates the local registry with the login context
credentials if the certification check succeeds.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
RETURN VALUES
The routine returns a boolean32 value that is TRUE if the certification
was successful, and FALSE otherwise.
ERRORS
sec_login_s_config
The DCE configuration (dce_config) information is not
available.
sec_login_s_context_invalid
The input context is invalid.
sec_login_s_default_use
It is an error to try to certify the default context.
error_status_ok
The call was successful.
EXAMPLES
Applications wishing to perform a straightforward login could use the
sec_login package as follows:
if (sec_login_setup_identity(user_name, sec_login_no_flags,
&login_context, &st)) {
... get password from user...
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
if (!sec_login_certify_identity(login_context, &st))
exit(error_weird_auth_svc);
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
if (reset_passwd) {
... get new password from user, reset registry record ...
};
sec_login_get_pwent(login_context, &pw_entry, &st);
if (pw_entry.pw_expire < todays_date) {
sec_login_purge_context(&login_context, &st);
exit(0)
}
... any other application specific login valid actions ...
}
} else {
sec_login_purge_context(&login_context, &st);
... application specific login failure actions ...
}
}
RELATED INFORMATION
Functions: sec_intro,
sec_login_get_pwent
sec_login_get_groups
sec_login_get_expiration
4.65 – sec_login_cred_get_delegate
NAME
sec_login_cred_get_delegate - Returns a handle to the privilege
attributes of an intermediary in a
delegation chain
Used by clients.
SYNOPSIS
#include <dce/sec_login.h>
sec_cred_pa_handle_t sec_login_cred_get_delegate(
sec_login_handle_t login_context,
sec_cred_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input
login_context
A value of sec_login_handle_t that provides an opaque handle to
a login context for which delegation has been enabled. The
sec_login_handle_t that specifies the identity is supplied
as output of the sec_login_become_delegate() call.
Input/Output
cursor
As input, a pointer to a cursor of type sec_cred_cursor_t that
has been initialized by the sec_login_cred_init_cursor() call.
As an output parameter, cursor is a pointer to a cursor of type
sec_cred_cursor_t that is positioned past the principal whose
privilege attributes have been returned in this call.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_cred_get_delegate() routine returns a handle of type
sec_login_handle_t to the the privilege attributes of an intermediary
in a delegation chain that performed an authenticated RPC operation.
This call is used by clients. Servers use the sec_cred_get_delegate()
routine to return the privilege attribute handle of an intermediary in
a delegation chain.
The login context identified by login_context contains all members in
the delegation chain. This call returns a handle (sec_cred_pa_handle_t)
to the privilege attributes of one of the delegates in the login
context. The sec_cred_pa_handle_t returned by this call is used in
other sec_cred_get... calls to obtain privilege attribute information
for a single delegate.
To obtain the privilege attributes of each delegate in the credential
handle identified by callers_identity, execute this call until the
message sec_cred_s_no_more_entries is returned.
Before you execute sec_login_cred_get_delegate(), you must execute a
sec_login_cred_init_cursor() call to initialize a cursor of type
sec_cred_cursor_t.
Use the sec_cred_free_pa_handle() sec_cred_free_cursor() calls to free
the resources allocated to the sec_cred_pa_handle_t and cursor.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_cred_s_invalid_cursor
sec_cred_s_no_more_entries
error_status_ok
EXAMPLES
RELATED INFORMATION
Functions: sec_intro
sec_login_cred_init_cursor
sec_cred_get_pa_date
sec_cred_get_extended_attrs
sec_cred_get_v1_pac
sec_cred_get_tgt_restrictions
sec_cred_get_deleg_restrictions
sec_cred_get_opt_restrictions
sec_cred_get_req_restrictions
sec_cred_get_delegation_type
4.66 – sec_login_cred_get_initiator
NAME
sec_login_cred_get_initiator - Returns information about the
delegation initiator in a specified
login context
SYNOPSIS
#include <dce/sec_login.h>
sec_cred_pa_handle_t sec_login_cred_get_initiator(
sec_login_handle_t login_context,
error_status_t *status);
PARAMETERS
Input
login_context
A value of sec_login_handle_t that provides an opaque handle
to a login context for which delegation has been enabled.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_cred_get_initiator() routine returns a handle of type
sec_cred_pa_handle_t to the privilege attributes of the delegation
initiator.
The login context identified by login_context contains all members in
the delegation chain. This call returns a handle (sec_cred_pa_handle_t)
to the privilege attributes of the initiator. The sec_cred_pa_handle_t
returned by this call is used in other sec_cred_get... calls to obtain
privilege attribute information for the initiator single delegate.
Use the sec_cred_free_pa_handle() call to free the resources allocated
to the sec_cred_pa_handle_t handle.
FILES
SYS$LIBRARY:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_invalid_context
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_cred_get_pa_date
sec_cred_get_extended_attrs
sec_cred_get_v1_pac
sec_cred_get_tgt_restrictions
sec_cred_get_deleg_restrictions
sec_cred_get_opt_restrictions
sec_cred_get_req_restrictions
sec_cred_get_delegation_type
4.67 – sec_login_cred_init_cursor
NAME
sec_login_cred_init_cursor - Initialize a sec_cred_cursor_t
SYNOPSIS
#include <dce/sec_cred.h>
void sec_login_cred_init_cursor (
sec_cred_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input/Output
cursor
As input, a pointer to a sec_cred_cursor_t to be initialized.
As output, a pointer to an initialized sec_cred_cursor_t.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_cred_init_cursor() routine allocates and initializes
a cursor of type sec_cursor_t for use with the
sec_login_cred_get_delegate() call.
Use the sec_cred_free_cursor() call to free the resources allocated to
cursor.
ERRORS
sec_cred_s_invalid_cursor
sec_login_s_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_login_cred_get_delegate
4.68 – sec_login_disable_delegation
NAME
sec_login_disable_delegation - Disables delegation for a specified
login context
SYNOPSIS
#include <dce/sec_login.h>
sec_logon_handle_t *sec_login_disable_delegation(
sec_login_handle_t login_context,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context for which delegation has been
enabled.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_disable_delegation() routine disables delegation for a
specified login context. It returns a new login context of type
sec_login_handle_t without any delegation information, thus preventing
any further delegation.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_invalid_context
error_status_ok
EXAMPLES
RELATED INFORMATION
Functions: sec_intro
sec_login_become_initiator
sec_login_become_delegate
sec_login_become_impersonator
4.69 – sec_login_export_context
NAME
sec_login_export_context - Creates an exportable login context
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_export_context(
sec_login_handle_t login_context,
unsigned32 buf_len,
idl_byte buf[],
unsigned32 *len_used,
unsigned32 *len_needed,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and UUID,
account restrictions, records of group membership, and the
process home directory. (See sec_intro for more details about
the login context.)
buf_len
An unsigned 32-bit integer containing the allocated length
(in bytes) of the buffer that is to contain the login context.
Output
buf[] An idl_byte array that contains the exportable login context upon
return.
len_used
A pointer to an unsigned 32-bit integer indicating the number of
bytes needed for the entire login context, up to buf_len.
len_needed
If the allocated length of the buffer is too short, an error is
issued (sec_login_s_no_memory), and on return this pointer
indicates the number of bytes necessary to contain the login
context.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_export_context() routine obtains an exportable version
of the login context information. This information may be passed to
another process running on the same machine.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_no_memory
Not enough space was allocated for the buf[] array. The
len_needed parameter will point to the needed length.
sec_login_s_handle_invalid
The login context handle is invalid.
sec_login_s_context_invalid
The login context specified by the input handle is
invalid.
RELATED INFORMATION
Functions: sec_intro
sec_login_import_context
4.70 – sec_login_free_net_info
NAME
sec_login_free_net_info - Frees storage allocated for a principal's
network information
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_free_net_info(
sec_login_net_info_t *net_info);
PARAMETERS
Input/Output
net_info
A pointer to the sec_login_net_info_t structure to be freed.
DESCRIPTION
The sec_login_free_net_info() routine frees any memory allocated for
a principal's network information. Network information is returned
by a previous successful call to sec_login_inquire_net_info().
CAUTIONS
This routine does not return any completion codes. Make sure that
you supply a valid sec_login_net_info_t address. The routine simply
frees a range of storage beginning at the supplied address, without
regard to the actual contents of the storage.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
RELATED INFORMATION
Functions: sec_intro
sec_login_inquire_net_info
4.71 – sec_login_get_current_context
NAME
sec_login_get_current_context - Returns a handle to the current
login context
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_get_current_context(
sec_login_handle_t *login_context,
error_status_t *status);
PARAMETERS
Output
login_context
A pointer to an opaque handle to login context data. The login
context contains, among other data, the account principal name
and UUID, account restrictions, records of group membership,
and the process home directory. (See sec_intro for more
details about the login context.)
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_get_current_context() routine retrieves a handle to the
login context for the currently established network identity. The
context returned is created from locally cached data so subsequent
data extraction operations may return some NULL values.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_no_current_context
There was no current context to retrieve. (See
sec_login_setup_identity for information about how
to set up, validate, and implement a login context.)
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the
sec_login_get_current_context() routine as part of a process to change
the groupset:
sec_login_get_current_context(&login_context, &st);
sec_login_get_groups(login_context, &num_groups, &groups, &st);
...the group IDs have to be converted from the returned UNIX
numbers into UUIDs (use sec_rgy_pgo_unix_num_to_id)...
for (i=0; i < num_groups; i++) {
... query whether the user wants to discard any of the current
group memberships. Copy new groupset to the new_groups array ...
}
if ( !sec_login_newgroups(sec_login_no_flags, num_new_groups,
new_groups, &login_context, &st)) {
if (st == sec_login_s_groupset_invalid)
printf("New groupset invalid0);
... application specific error handling ...
}
RELATED INFORMATION
Functions: sec_intro
sec_login_setup_identity
4.72 – sec_login_get_expiration
NAME
sec_login_get_expiration - Returns the TGT lifetime for an
authenticated identity
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_get_expiration(
sec_login_handle_t login_context,
signed32 *identity_expiration,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and
UUID, account restrictions, records of group membership, and
the process home directory. (See sec_intro for more details
about the login context.)
Output
identity_expiration
The lifetime of the Ticket-Granting Ticket (TGT) belonging to
the authenticated identity identified by login_context. It can
be used in the same ways as a UNIX time_t.
status
A pointer to the completion status. On successful completion,
the routine returns one of the following status codes:
+ error_status_ok to indicate that the login context has been
validated and certified.
+ sec_login_s_not_certified to indicate that the login context
has been validated, but not certified. Although this code
indicates successful completion, it warns you that the
context is not validated.
If the call does not complete successfully, it returns an error.
DESCRIPTION
The sec_login_get_expiration() routine extracts the lifetime for the
TGT belonging to the authenticated identity contained in the login
context. The liftime value is filled in if available; otherwise, it
is set to 0 (zero). This routine allows an application to tell an
interactive user how long the user's network login (and authenticated
identity) will last before having to be refreshed.
The routine works only on previously certified contexts.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_context_invalid
The login context itself is invalid.
sec_login_s_default_use
There was illegal use of the default login handle.
sec_login_s_not_certified
The login context has not been certified.
sec_login_s_no_current_context
The calling process has no context of its own.
error_status_ok
The call was successful.
EXAMPLES
Since the authenticated network identity for a process has a finite
lifetime, there is a risk it will expire during some long network
operation, preventing the operation from completing. To avoid this
situation, an application might, before initiating a long operation,
use the sec_login package to check the expiration time of its identity
and refresh it if there is not enough time remaining to complete the
operation. After refreshing the identity, the process must validate it
again with sec_login_validate_identity().
sec_login_get_expiration(login_context, &expire_time, &st);
if (expire_time < (current_time + operation_duration)) {
if (!sec_login_refresh_identity(login_context, &st)) {
if (st == sec_login_s_refresh_ident_bad) {
... identity has changed ...
} else {
... login context cannot be renewed ...
exit(error_context_not_renewable);
}
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
... identity validated ...
} else {
... validation failed ...
exit(error_validation_failure);
}
}
}
operation();
RELATED INFORMATION
Functions: sec_intro
sec_login_get_current_context
4.73 – sec_login_get_groups
NAME
sec_login_get_groups - Returns the groupset from a login context
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_get_groups(
sec_login_handle_t login_context,
unsigned32 *num_groups,
signed32 **group_set,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and UUID,
account restrictions, records of group membership, and the
process home directory. (See sec_intro for more details about
the login context.)
Output
num_groups
An unsigned 32-bit integer indicating the total number of groups
returned in the group_set array.
group_set
The list of groups to which the user belongs.
status
A pointer to the completion status. On successful completion,
the routine returns one of the following status codes:
+ error_status_ok to indicate that the login context has
been validated and certified.
+ sec_login_s_not_certified to indicate that the login context
has been validated, but not certified. Although this code
indicates successful completion, it warns you that the
context is not validated.
If the call does not complete successfully, it returns an error.
DESCRIPTION
The sec_login_get_groups() routine returns the groups contained in the
supplied login context. Part of a network identity is a list of the
various groups to which the principal belongs. The groups are used to
determine a user's access to various objects and services. This
routine extracts from the login context a list of the groups for which
the user has established network privileges.
The routine works only on previously validated contexts.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_context_invalid
The login context itself is not valid.
sec_login_s_info_not_avail
The login context has no UNIX information.
sec_login_s_default_use
Illegal use of the default login handle occurred.
sec_login_s_not_certified
The login context has not been certified.
sec_login_s_not_certified
The login context is not certified.
sec_rgy_object_not_found
The registry server could not find the specified
login context data.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the sec_login_get_groups()
routine as part of a process to change the groupset:
sec_login_get_current_context(&login_context, &st);
sec_login_get_groups(login_context, &num_groups, &groups, &st);
...the group IDs have to be converted from the returned UNIX
numbers into UUIDs (use sec_rgy_pgo_unix_num_to_id)...
for (i=0; i < num_groups; i++) {
... query whether the user wants to discard any of the current
group memberships. Copy new groupset to the new_groups array ...
}
if ( !sec_login_newgroups(sec_login_no_flags, num_new_groups,
new_groups, &login_context, &st)) {
if (st == sec_login_s_groupset_invalid)
printf("New groupset invalid0);
... application specific error handling ...
}
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_get_projlist
4.74 – sec_login_get_pwent
NAME
sec_login_get_pwent - Returns a passwd-style entry for a login context
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_get_pwent(
sec_login_handle_t login_context,
sec_login_passwd_t *pwent,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and UUID,
account restrictions, records of group membership, and the
process home directory. (See sec_intro for more details about
the login context.)
Output
pwent A pointer to a pointer to the returned passwd-style structure.
The particular structure depends on the underlying system. For
example, on a system with a passwd structure like that supported
by 4.4BSD and OSF/1, the structure (found in /usr/include/pwd.h)
is:
struct passwd {
char *pw_name; /* user name */
char *pw_passwd; /* encrypted password */
int pw_uid; /* user uid */
int pw_gid; /* user gid */
time_t pw_change; /* password change time */
char *pw_class; /* user access class */
char *pw_gecos; /* miscellaneous account info */
char *pw_dir; /* home directory */
char *pw_shell; /* default shell */
time_t pw_expire; /* account expiration */
};
status
A pointer to the completion status. On successful completion,
the routine returns one of the following status codes:
+ error_status_ok to indicate that the login context has
been validated and certified.
+ sec_login_s_not_certified to indicate that the login context
has been validated, but not certified. Although this code
indicates successful completion, it warns you that the
context is not validated.
If the call does not complete successfully, it returns an error.
DESCRIPTION
The sec_login_get_pwent() routine creates a passwd-style structure for
the current network login context. This is generally useful for
establishing the local operating system context. Applications that
require all of the data normally extracted via getpwnam() should extract
that data from the login context with this call.
This routine works only on explicitly created (not inherited or
imported) contexts.
CAUTIONS
The returned sec_login_passwd_t structure points to data stored in
the structure indicated by the login_context pointer and must be
treated as read-only data. Writing to these data objects may cause
unexpected failures.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
EXAMPLES
The following example illustrates use of the sec_login_get_pwent()
routine:
#include <pwd.h>
struct passwd *pwd;
sec_login_get_pwent( login_context,
&(sec_login_passwd_t*)pwd,&status );
printf ("%s",pwd->pw_name);
ERRORS
sec_login_s_context_invalid
The login context itself is invalid.
sec_login_s_not_certified
The login context has not been certified.
sec_login_s_default_use
Illegal use of the default login handle occurred.
sec_login_s_info_not_avail
The login context has no UNIX information.
sec_rgy_object_not_found
The registry server could not find the specified login
context data.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
4.75 – sec_login_import_context
NAME
sec_login_import_context - Imports a login context
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_import_context(
unsigned32 buf_len,
idl_byte buf[],
sec_login_handle_t *login_context,
error_status_t *status);
PARAMETERS
Input
buf_len
The allocated length (in bytes) of the buffer containing the
login context.
buf[] An idl_byte array containing the importable login context.
Output
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and UUID,
account restrictions, records of group membership, and the
process home directory. (See sec_intro for more details about
the login context.)
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_import_context() routine imports a context obtained via
a call to sec_login_export_context() performed on the same machine. To
import a login context, users must have the appropriate privileges.
Nonprivileged users can import only their own login context; privileged
users can import the login contexts created by any users.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_context_invalid
The login context itself is not valid.
sec_login_s_default_use
Illegal use of the default login handle occurred.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_login_export_context
4.76 – sec_login_init_first
NAME
sec_login_init_first - Initializes the default context
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_init_first(
error_status_t *status);
PARAMETERS
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_init_first() routine initializes the default context
inheritance mechanism. If the default inheritance mechanism is already
initialized, the operation fails. Typically, this routine is called by
the initial process at machine boot time to initialize the default
context inheritance mechanism for the host machine process hierarchy.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_default_use
The default context is already initialized.
sec_login_s_privileged
An unprivileged process was called in.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_login_setup_first
sec_login_validate_first
4.77 – sec_login_inquire_net_info
NAME
sec_login_inquire_net_info - Returns a principal's network information
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_inquire_net_info(
sec_login_handle_t login_context,
sec_login_net_info_t *net_info,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to the login context for the desired principal.
(See sec_intro for more details about the login context.)
Output
net_info
A pointer to the returned sec_login_net_info_t data structure
that contains the principal's network information. The
sec_login_net_info_t structure is defined as follows:
typedef struct {
sec_id_pac_t pac;
unsigned32 acct_expiration_date;
unsigned32 passwd_expiration_date;
unsigned32 identity_expiration_date;
} sec_login_net_info_t;
};
status
A pointer to the completion status. On successful completion,
the routine returns one of the following status codes:
+ error_status_ok to indicate that the principal's network
information returned in the sec_login_net_info_t data
structure has been validated and certified.
+ sec_login_s_not_certified to indicate that the principal's
network information returned in the sec_login_net_info_t
data structure has been validated, but not certified.
Although this code indicates successful completion, it
warns you that the information is not validated.
If the call does not complete successfully, it returns an error.
DESCRIPTION
The sec_login_inquire_net_info() routine returns network information
for the principal identified by the specified login context. The
network information consists of the following:
+ The Privilege Attribute Certificate (PAC) that describes the
identity and group memberships of the principal.
+ The expiration date for the principal's account in the DCE
Registry.
+ The expiration date for the principal's password in the DCE
Registry.
+ The lifetime for the principal's authenticated network identity.
This is the lifetime of the principal's TGT (see the
sec_login_get_expiration() routine).
A value of 0 (zero) for an expiration date means there is no
expiration date. In other words, the principal's account, password,
or authenticated identity is good indefinitely.
To remove the returned net_info structure when it is no longer needed,
use sec_login_free_net_info().
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_not_certified
The login context is not certified.
sec_login_s_context_invalid
The login context is not valid.
sec_login_s_no_current_context
The default context was specified, but none exists.
sec_login_s_auth_local
Operation not valid on local context. The call's identity
was not authenticated.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_login_get_expiration
sec_login_free_net_info
4.78 – sec_login_newgroups
NAME
sec_login_newgroups - Changes the group list for a login context
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_newgroups(
sec_login_handle_t login_context,
sec_login_flags_t flags,
unsigned32 num_local_groups,
sec_id_t local_groups[],
sec_login_handle_t *restricted_context,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and
UUID, account restrictions, records of group membership, and
the process home directory. (See sec_intro for more details
about the login context.)
flags A set of flags of type sec_login_flags_t. These contain
information about how the new network credentials will be used.
Currently, the only flag used is sec_login_credentials_private,
that, when set, implies that the new context is only to be used
by the calling process. If this flag is not set (flags =
sec_login_no_flags), descendants of the calling process may
also use the new network credentials.
num_local_groups
An unsigned 32-bit integer containing the number of local group
identities to include in the new context.
local_groups[]
An array of sec_id_t elements. Each element contains the UUID
of a local group identity to include in the new context. These
identities are local to the cell. Optionally, each element may
also contain a pointer to a character string containing the
name of the local group.
Output
restricted_context
An opaque handle to the login context containing the changed
group list.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_newgroups() routine changes the group list for the
specified login context. Part of a network identity is a list of the
various groups to which a principal belongs. The groups are used to
determine a user's access to various objects and services. This
routine returns a new login context that contains the changed group
list. To remove the new login context when it is no longer needed,
use sec_login_purge_context().
This operation does not need to be validated as the user identity does
not change. Consequently, knowledge of the password is not needed.
NOTES
urrently you can have only groups from the local cell.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
RETURN VALUES
This routine returns TRUE when the new login context is successfully
established.
ERRORS
sec_login_s_auth_local
Operation not valid on local context.
sec_login_s_default_use
It is an error to try to certify the default context.
sec_login_s_groupset_invalid
The input list of group names is invalid. There may be
groups to which the caller does not belong, or the list
may contain groups that do not exist.
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the sec_login_newgroups()
routine as part of a process to change the groupset:
sec_login_get_current_context(&login_context, &st);
sec_login_get_groups(login_context, &num_groups, &groups, &st);
...the group IDs have to be converted from the returned UNIX
numbers into UUIDs (use sec_rgy_pgo_unix_num_to_id)...
for (i=0; i < num_groups; i++) {
... query whether the user wants to discard any of the
current group memberships. Copy new groupset to the new_groups
array ...
}
if ( !sec_login_newgroups(sec_login_no_flags, num_new_groups,
new_groups, &login_context, &st)) {
if (st == sec_login_s_groupset_invalid)
printf("New groupset invalid0);
... application specific error handling ...
}
RELATED INFORMATION
Functions: sec_intro
sec_login_get_groups
sec_login_purge_context
4.79 – sec_login_purge_context
NAME
sec_login_purge_context - Destroys a login context and frees its
storage
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_purge_context(
sec_login_handle_t *login_context,
error_status_t *status);
PARAMETERS
Input
login_context
A pointer to an opaque handle to login context data. The login
context contains, among other data, the account principal name
and UUID, account restrictions, records of group membership,
and the process home directory. (See sec_intro for more details
about the login context.) Note that a pointer to the handle is
submitted, so the handle may be reset to NULL upon successful
completion.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_purge_context() routine frees any storage allocated
for the specified login context and destroys the associated network
credentials, if any exist.
CAUTIONS
Applications must be cautious when purging the current context as
this destroys network credentials for all processes that share the
credentials.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_default_use
Illegal use of the default login handle occurred.
sec_login_s_context_invalid
The login context itself is not valid.
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the sec_login_purge_context()
routine as part of a straightforward login process:
if (sec_login_setup_identity( user_name,
sec_login_no_flags,
&login_context,
&st)) {
... get password from user...
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
if (!sec_login_certify_identity(login_context, &st))
exit(error_wierd_auth_svc);
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
if (reset_passwd) {
... get new password from user, reset registry record ...
};
sec_login_get_pwent(login_context, &pw_entry, &st);
if (pw_entry.pw_expire < todays_date) {
sec_login_purge_context(&login_context, &st);
exit(0)
}
... any other application specific login valid actions ...
}
} else {
sec_login_purge_context(&login_context, &st);
... application specific login failure actions ...
}
}
RELATED INFORMATION
Functions: sec_intro
sec_login_set_context
sec_login_setup_identity
sec_login_validate_identity
4.80 – sec_login_refresh_identity
NAME
sec_login_refresh_identity - Refreshes an authenticated identity for
a login context
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_refresh_identity(
sec_login_handle_t login_context,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and
UUID, account restrictions, records of group membership, and
the process home directory.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_refresh_identity() routine refreshes a previously
established identity. It operates on an existing valid context, and
cannot be used to change credentials associated with that identity.
The refreshed identity reflects changes that affect ticket lifetimes,
but not other changes. For example, the identity will reflect a change
to maximum ticket lifetime, but not the addition of the identity as a
member to a group. Only a DCE login reflects all administrative
changes made since the last login.
The refreshed identity must be validated with
sec_login_validate_identity() before it can be used.
It is an error to refresh a locally authenticated context.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_context_invalid
The login context itself is not valid.
sec_login_s_default_use
Illegal use of the default login handle occurred.
sec_login_s_no_memory
Not enough memory is available to complete the operation.
error_status_ok
The call was successful.
EXAMPLES
Since the authenticated network identity for a process has a finite
lifetime, there is a risk it will expire during some long network
operation, preventing the operation from completing.
For a server application that must run with an authenticated network
identity because they themselves sometimes act as clients of another
server, the sec_login calls can be used to check the network identity
expiration date, run sec_login_refresh_identity and
sec_login_validate_identity before the expiration. This will prevent
interruptions in the server's operation due to the restrictions in
network access applied to an unauthenticated identity.
sec_login_get_expiration(login_context, &expire_time, &st);
if (expire_time < (current_time + operation_duration)) {
if (!sec_login_refresh_identity(login_context, &st)) {
... login context cannot be renewed ...
... sleep and try again ....
}
} else {
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
... identity validated ...
} else {
... validation failed ...
exit(error_validation_failure);
}
}
}
operation();
RELATED INFORMATION
Functions: sec_intro
sec_login_validate_identity
4.81 – sec_login_release_context
NAME
sec_login_release_context - Frees storage allocated for a login
context
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_release_context(
sec_login_handle_t *login_context,
error_status_t *status);
PARAMETERS
Input/Output
login_context
A pointer to an opaque handle to login context data. The login
context contains, among other data, the account principal name
and UUID, account restrictions, records of group membership,
and the process home directory. (See sec_intro for more details
about the login context.)
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_release_context() routine frees any memory allocated
for a login context. Unlike sec_login_purge_context(), it does not
destroy the associated network credentials that still reside in the
credential cache.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_default_use
Illegal use of the default login handle occurred.
sec_login_s_context_invalid
The login context itself is invalid.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_login_purge_context
4.82 – sec_login_set_context
NAME
sec_login_set_context - Creates network credentials for a login
context
SYNOPSIS
#include <dce/sec_login.h>
void sec_login_set_context(
sec_login_handle_t login_context,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and
UUID, account restrictions, records of group membership, and
the process home directory. (See sec_intro for more details
about the login context.)
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_set_context() routine sets the network credentials
to those specified by the login context. This context must have
been previously validated. Contexts acquired through
sec_login_get_current_context() or sec_login_newgroups() do not
need to be validated since those routines return previously
alidated contexts.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_context_invalid
The login context itself is invalid.
sec_login_s_default_use
Illegal use of the default login handle occurred.
sec_login_s_auth_local
Operation not valid on local context.
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the sec_login_set_context()
routine as part of a straightforward login process:
if (sec_login_setup_identity( user_name,
sec_login_no_flags,
&login_context,
&st )) {
... get password from user...
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
if (!sec_login_certify_identity(login_context, &st))
exit(error_weird_auth_svc);
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
if (reset_passwd) {
... get new password from user, reset registry record ...
};
sec_login_get_pwent(login_context, &pw_entry, &st);
if (pw_entry.pw_expire < todays_date) {
sec_login_purge_context(&login_context, &st);
exit(0)
}
... any other application specific login valid actions ...
}
} else {
sec_login_purge_context(&login_context, &st);
... application specific login failure actions ...
}
}
RELATED INFORMATION
Functions: sec_intro
sec_login_setup_identity
sec_login_validate_identity
4.83 – sec_login_set_extended_attrs
NAME
sec_login_set_extended_attrs - Constructs a new login context that
contains extended registry attributes
SYNOPSIS
#include <dce/sec_login.h>
sec_login_handle_t sec_login_set_extended_attrs(
sec_login_handle_t my_login_context,
unsigned32 num_attributes,
sec_attr_t attributes[]
error_status_t *status);
PARAMETERS
Input
my_login_context
A value of sec_login_handle_t that provides an opaque handle
to the identity of the calling client.
num_attributes
An unsigned 32-bit integer that specifies the number of elements
in the attributes[] array. The number must be greater than 0.
attributes[]
An array of values of type sec_attr_t that specifies the list of
attributes to be set in the new login context.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_set_extended_attrs() constructs a login context that
contains extended registry attributes that have been established for
the object identified by my_login_context. The attributes themselves
must have been established and attached to the object using the
Extended Registry Attribute API.
The input attributes[] array of sec_attr_t values should specify the
attr_id field for each requested attribute. Since the lookup is by
attribute type ID only, set the attribute.attr_value.attr_encoding
field to sec_attr_enc_void for each attribute. Note that sec_attr_t
is an Extended Registry Attribute data type. For more information on
Extended Registry Attributes, see the description of the sec_attr calls
in this document and the chapter titled "The Extended Registry
Attribute API" in the DCE Application Development Guide.
You cannot use this call to add extended registry attributes to a
delegation chain. If you pass in a login context that refers to a
delegation chain, an invalid context error will be returned.
The routine returns a new login context of type sec_login_handle_t
that includes the attributes specified in the attributes[] array.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_invalid_context
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_... calls
sec_login_become_impersonator
sec_login_setup_identity
sec_login_validate_identity
sec_login_set_context
4.84 – sec_login_setup_first
NAME
sec_login_setup_first - Sets up the default network context
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_setup_first(
sec_login_handle_t *init_context,
error_status_t *status);
PARAMETERS
Output
init_context
A pointer to an opaque handle to login context data. The login
context contains, among other data, the account principal name
and UUID, account restrictions, records of group membership,
and the process home directory. In this call, the context will
be that of the host machine initial process. (See sec_intro
for more details about the login context.)
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_setup_first() routine sets up the default context
network identity. If the default context already contains valid
credentials, the routine fails. Typically, this routine is called
from the Security Validation Service of the dced process to breathe
life into the default credentials for the host machine process
hierarchy.
This routine uses the hostname available via the local dce_config
interface as the principal name for the setup, so it does need a
principal name as input.
RETURN VALUES
The routine returns a boolean32 value that is TRUE if the setup was
successful, and FALSE otherwise.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_default_use
The default context is already in use and does not need
to be set up again.
sec_login_s_no_current_context
The calling process has no context of its own.
sec_login_s_privileged
An unprivileged process was called in.
sec_login_s_config
The DCE configuration (dce_config) information is not
available.
sec_rgy_object_not_found
The principal does not exist.
sec_rgy_server_unavailable
The network registry is not available.
sec_login_s_no_memory
A memory allocation error occurred.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_login_init_first
sec_login_validate_first
4.85 – sec_login_setup_identity
NAME
sec_login_setup_identity - Sets up the user's network identity
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_setup_identity(
unsigned_char_p_t principal,
sec_login_flags_t flags,
sec_login_handle_t *login_context,
error_status_t *status);
PARAMETERS
Input
principal
A pointer (type unsigned_char_p_t) indicating a character
string containing the principal name on the registry account
corresponding to the calling process.
flags A set of flags of type sec_login_flags_t. These contain
information about how the new network credentials are to be used.
Output
login_context
A pointer to an opaque handle to login context data. The login
context contains, among other data, the account principal name
and UUID, account restrictions, records of group membership,
and the process home directory. (See sec_intro for more details
about the login context.)
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_setup_identity() routine creates any local context
necessary to perform authenticated network operations. It does not
establish any local operating system context; that is the
responsibility of the caller. It is the standard network login
function. The network identity set up by this operation cannot be
used until it is validated via sec_login_validate_identity().
The sec_login_setup_identity() operation and the
sec_login_validate_identity() operation are two halves of a single
logical operation. Together they collect the identity data needed
to establish an authenticated identity.
NOTES
Neither sec_login_setup_identity() nor sec_login_validate_identity()
check for account or identity expiration. The application program
using this interface is responsible for such checks.
RETURN VALUES
The routine returns TRUE if the identity has been successfully
established.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_rgy_object_not_found
The principal does not exist.
sec_rgy_server_unavailable
The network registry is not available.
sec_login_s_no_memory
Not enough memory is available to complete the operation.
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the sec_login_setup_identity()
routine as part of a straightforward login process:
if (sec_login_setup_identity( user_name,
sec_login_no_flags,
&login_context,
&st )) {
... get password from user...
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
if (!sec_login_certify_identity(login_context, &st))
exit(error_weird_auth_svc);
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
if (reset_passwd) {
... get new password from user, reset registry record ...
};
sec_login_get_pwent(login_context, &pw_entry, &st);
if (pw_entry.pw_expire < todays_date) {
sec_login_purge_context(&login_context, &st);
exit(0)
}
... any other application specific login valid actions ...
}
} else {
sec_login_purge_context(&login_context, &st);
... application specific login failure actions ...
}
}
RELATED INFORMATION
Functions: sec_intro
sec_login_validate_identity
sec_login_set_context
4.86 – sec_login_valid_and_cert_ident
NAME
sec_login_valid_and_cert_ident - Validates and certifies a login
context
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_valid_and_cert_ident(
sec_login_handle_t login_context,
sec_passwd_rec_t *passwd,
boolean32 *reset_passwd,
sec_login_auth_src_t *auth_src,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and
UUID, account restrictions, records of group membership, and
the process home directory. (See sec_intro for more details
about the login context.)
passwd
A password record to be checked against the password in the
principal's registry account. The routine returns TRUE if the
two match. The contents of the passwd parameter are erased
after the call has finished processing it.
Output
reset_passwd
A pointer to a 32-bit boolean32 value. The routine returns
TRUE if the account password has expired and must be reset.
auth_src
A 32-bit set of flags identifying the source of the
authentication. Upon return after successful authentication,
the flags in auth_src indicate what authority was used to
validate the login context. If the authentication was
accomplished with the network authority, the
sec_login_auth_src_network flag is set, and the process login
context has credentials to use the network. If the
authentication was accomplished with local data only (either
the principal's account is tailored for the local machine
with overrides, or the network authority is unavailable), the
sec_login_auth_src_local flag is set. Login contexts that are
authenticated locally may not be used to establish network
credentials because they have none.
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_valid_and_cert_ident() routine validates and certifies
a login context established with sec_login_setup_identity(). The
caller must supply the user's password as input with the passwd
parameter.
This routine combines the operations of the
sec_login_validate_identity() and sec_login_certify_identity()
routines. It is intended for use by system login programs that
need to extract trustworthy operating system credentials for use
in setting the local identity for a process. This operation
destroys the contents of the passwd input parameter.
If the network security service is unavailable or if the user's
password has been overridden on the host, a locally authenticated
context is created, and the auth_src parameter is set to
sec_login_auth_src_local. Data extracted from a locally
authenticated context may be used to set the local OS identity, but
it cannot be used to establish network credentials.
This routine is a privileged operation.
RETURN VALUES
The routine returns TRUE if the login identity has been successfully
validated.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_rgy_passwd_invalid
The input string does not match the account password.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
sec_login_s_acct_invalid
The account is invalid or has expired.
sec_login_s_privileged
This is a privileged operation and was invoked by an
unprivileged process.
sec_login_s_null_password
The input string is NULL.
sec_login_s_default_use
The input context was the default context, which cannot be
validated.
sec_login_s_already_valid
The login context has already been validated.
sec_login_s_unsupp_passwd_type
The password type is not supported.
sec_login_s_no_memory
Not enough memory is available to complete the operation.
sec_login_s_preauth_failed
Preauthentication failure.
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the
sec_login_valid_and_cert_ident() routine as part of a system login
process:
if (sec_login_setup_identity(<user>,
sec_login_no_flags, &login_context, &st)) {
... get password ...
if (sec_login_valid_and_cert_ident(login_context,
password, &st)) {
if (auth_src == sec_login_auth_src_network) {
if (GOOD_STATUS(&st)
sec_login_set_context(login_context);
}
}
if (reset_passwd) {
... reset the user's password ...
if (passwd_reset_fails) {
sec_login_purge_context(login_context)
... application login failure actions ...
}
... application specific login valid actions ...
}
}
RELATED INFORMATION
Functions: sec_intro
sec_login_certify_identity
sec_login_setup_identity
sec_login_validate_identity
4.87 – sec_login_valid_from_keytable
NAME
sec_login_valid_from_keytable - Validates a login context's
identit using input from a
specified keytable file
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_valid_from_keytable(
sec_login_handle_t login_context,
unsigned32 authn_service,
void *arg,
unsigned32 try_kvno,
unsigned32 *used_kvno,
boolean32 *reset_passwd,
sec_login_auth_src_t *auth_src,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal's name and
UUID, account restrictions, records of the account principal's
group memberships, and the account's home directory. (See
sec_intro for more details about the login context.)
authn_service
Identifies the authentication protocol using the key. The
possible authentication protocols are as follows:
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
arg This parameter can specify either the local keytab file or an
argument to the get_key_fn key acquisition routine of the
rpc_server_register_auth_info routine.
A value of NULL specifies that the default keytab file should
be used. A keytab file name specifies that that file should be
used as the keytab file. You must prepend the file's absolute
filename with FILE: and the file must have been created with
the rgy_edit command or the sec_key_mgmt_set_key routine.
Any other value specifies an argument for the get_key_fn key
acquisition routine. See the rpc_server_register_auth_info()
reference page for more information.
try_kvno
The version number of the key in the keytab file to try first.
Specify NULL to try the current version of the key.
Output
used_kvno
A pointer to a 32-bit boolean32 value that specifies the
version number of the the key from the keytab file that was
used to successfully validate the login context, if any.
reset_passwd
A pointer to a 32-bit boolean32 value. The routine returns
TRUE if the account password has expired and should be reset.
auth_src
How the the login context was authorized. The
sec_login_auth_src_t data type distinguishes the various
ways the login context was authorized. There are three possible
values:
sec_login_auth_src_network
Authentication accomplished through the normal network
authority. A login context authenticated this way will
have all the network credentials it ought to have.
sec_login_auth_src_local
Authentication accomplished via local data.
Authentication occurs locally if a principal's
account is tailored for the local machine, or if
the network authority is unavailable. Since a login
contexts authenticated locally has no network
credentials, it can not be used for network
operations.
sec_login_auth_src_overridden
Authentication accomplished via the override facility.
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_valid_from_keytable () routine validates the login
context established with sec_login_setup_identity(). The
sec_login_valid_from_keytable () routine obtains the principal's
password from the specified keytable.
If try_kvno specifies a key version number, that version number key
is tried first, otherwise the current key version number is tried first.
The function trys all keys in the keytable until it finds one that
validates the login context. This operation must be invoked before the
network credentials can be used.
NOTES
A context is not secure and must not be set or exported until the
authentication service is itself authenticated with the
sec_login_certify_identity() call.
RETURN VALUES
The routine returns TRUE if the login context has been successfully
validated.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_rgy_passwd_invalid
The input string does not match the account password.
sec_rgy_server_unavailable
There is no data with which to compare the input string.
sec_login_s_acct_invalid
The account is invalid or has expired.
sec_login_s_default_use
The input context was the default context, which cannot
be validated.
sec_login_s_already_valid
The login context has already been validated.
sec_login_s_unsupp_passwd_type
The password type is not supported.
sec_key_mgmt_e_key_unavailable
The requested key is not present.
sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.
sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.
sec_s_no_memory
Unable to allocate memory.
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the
sec_login_valid_from_keytable() routine as part of a straightforward
login process:
if (sec_login_setup_identity( user_name,
sec_login_no_flags,
&login_context,
&st )) {
... get password from local keytable...
if (sec_login_valid_from_keytable( login_context,
authn_service,
arg,
try_kvno,
&used_kvno,
&reset_passwd,
&auth_src,
&st )) {
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
}
... any other application specific login valid actions ...
}
} else {
sec_login_purge_context(&login_context, &st);
... application specific login failure actions ...
}
}
RELATED INFORMATION
Functions: sec_intro
sec_login_validate_identity
sec_login_certify_identity
sec_login_setup_identity
sec_login_valid_and_cert_ident
4.88 – sec_login_validate_first
NAME
sec_login_validate_first - Validates the initial login context
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_validate_first(
sec_login_handle_t init_context,
boolean32 *reset_passwd,
sec_login_auth_src_t *auth_src,
error_status_t *status);
PARAMETERS
Input
init_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and
UUID, account restrictions, records of group membership,
and the process home directory. In this call, the context
will be that of the host machine initial process. (See
sec_intro for more details about the login context.)
Output
reset_passwd
A pointer to a 32-bit boolean32 value. The routine returns
TRUE if the account password has expired and must be reset.
auth_src
A 32-bit set of flags identifying the source of the
authentication. Upon return after successful authentication,
the flags in auth_src indicate what authority was used to
validate the login context. If the authentication was
accomplished with the network authority, the
sec_login_auth_src_network flag is set, and the process login
context has credentials to use the network. If the
authentication was accomplished with local data only (either
the principal's account is tailored for the local machine with
overrides, or the network authority is unavailable), the
sec_login_auth_src_local flag is set. Login contexts that are
authenticated locally may not be used to establish network
credentials because they have none.
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_validate_first() routine validates the default login
context established via sec_login_setup_first(). Typically, this
operation is called from the Security Validation Service of the dced
process to validate the default credentials for the host machine
process hierarchy. This operation uses the password for the local
host, and therefore does not require a password parameter.
RETURN VALUES
The routine returns a boolean32 value that is TRUE if the setup was
successful, and FALSE otherwise.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_login_s_privileged
An unprivileged process was called in.
sec_rgy_server_unavailable
The network authentication service was unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_login_init_first
sec_login_setup_first
4.89 – sec_login_validate_identity
NAME
sec_login_validate_identity - Validates a login context's identity
SYNOPSIS
#include <dce/sec_login.h>
boolean32 sec_login_validate_identity(
sec_login_handle_t login_context,
sec_passwd_rec_t *passwd,
boolean32 *reset_passwd,
sec_login_auth_src_t *auth_src,
error_status_t *status);
PARAMETERS
Input
login_context
An opaque handle to login context data. The login context
contains, among other data, the account principal name and
UUID, account restrictions, records of group membership, and
the process home directory. (See sec_intro for more details
about the login context.)
passwd
A password record to be checked against the password in the
principal's registry account. The routine returns TRUE if the
two match. The contents of the passwd parameter are erased
after the call has finished processing it.
Output
reset_passwd
A pointer to a 32-bit boolean32 value. The routine returns
TRUE if the account password has expired and must be reset.
auth_src
How the the login context was authorized. The
sec_login_auth_src_t data type distinguishes the various
ways the login context was authorized. There are three
possible values:
sec_login_auth_src_network
sec_login_auth_src_local
sec_login_auth_src_overridden
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_login_validate_identity() routine validates the login context
established with sec_login_setup_identity(). This operation must be
invoked before the network credentials can be used. The caller must
supply the user's password in a sec_passwd_rec_t as input with the
passwd parameter. The following example sets up a plaintext password
for the passwd parameter:
sec_passwd_str_t tmp_passwd;
passwd.version_number = sec_passwd_c_version_none;
passwd.pepper = NULL;
passwd.key.key_type = sec_passwd_plain;
strncpy( (char *) tmp_passwd,
(char *) my_passwd,
sec_passwd_str_max_len );
tmp_passwd[sec_passwd_str_max_len] = ' ';
passwd_rec.key.tagged_union.plain = &(tmp_passwd[0]);
When a network identity is set, only state information for network
operations has been established. The local operating system identity
has not been modified. It is the responsibility of the caller to
establish any local operating identity state.
The sec_login_setup_identity() operation and the
sec_login_validate_identity() operation are two halves of a single
logical operation. Together they collect the identity data needed
to establish an authenticated identity. The operations are independent
so the user's password need not be sent across the network. The
identity validation performed by sec_login_validate_identity() is a
local operation.
NOTES
A context is not secure and must not be set or exported until the
authentication service is itself authenticated with the
sec_login_certify_identity() call.
System login programs that set local operating system identity
using data extracted from a login context should use
sec_login_valid_and_cert_ident() instead of
sec_login_validate_identity().
If the Security server and client clocks are not synchronized to
within 2 to 3 minutes of each other, this call can return a password
validation error.
RETURN VALUES
The routine returns TRUE if the login identity has been successfully
validated.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
sec_rgy_passwd_invalid
The input string does not match the account password.
sec_rgy_server_unavailable
There is no data with which to compare the input string.
sec_login_s_acct_invalid
The account is invalid or has expired.
sec_login_s_null_password
The input string is NULL.
sec_login_s_default_use
The input context was the default context, which cannot
be validated.
sec_login_s_already_valid
The login context has already been validated.
sec_login_s_unsupp_passwd_type
The password type is not supported.
sec_login_s_no_memory
Not enough memory is available to complete the operation.
sec_login_s_preauth_failed
Preauthentication failure.
error_status_ok
The call was successful.
EXAMPLES
The following example illustrates use of the
sec_login_validate_identity() routine as part of a
straightforward login process:
if (sec_login_setup_identity( user_name,
sec_login_no_flags,
&login_context,
&st )) {
... get password from user...
if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
if (!sec_login_certify_identity(login_context, &st))
exit(error_weird_auth_svc);
sec_login_set_context(login_context, &st);
if (auth_src != sec_login_auth_src_network)
printf("no network credentials");
if (reset_passwd) {
... get new password from user, reset registry record ...
};
sec_login_get_pwent(login_context, &pw_entry, &st);
if (pw_entry.pw_expire < todays_date) {
sec_login_purge_context(&login_context, &st);
exit(0)
}
... any other application specific login valid actions ...
}
} else {
sec_login_purge_context(&login_context, &st);
... application specific login failure actions ...
}
}
RELATED INFORMATION
Functions: sec_intro
sec_login_certify_identity
sec_login_setup_identity
sec_login_valid_and_cert_ident
4.90 – sec_pwd_mgmt_free_handle
NAME
sec_pwd_mgmt_free_handle - Frees storage allocated for a
password management handle
SYNOPSIS
#include <dce/sec_pwd_mgmt.h>
void sec_pwd_mgmt_free_handle(
sec_pwd_mgmt_handle_t *pwd_mgmt_h,
error_status_t *stp
)
PARAMETERS
Input/Output
pwd_mgmt_h
A handle to the password management data which is to be freed.
Output
stp A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_pwd_mgmt_free_handle() routine frees any memory allocated for
the contents of a password management handle.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_PWD_MGMT.IDL
The idl file from which dce/sec_pwd_mgmt.h was derived.
ERRORS
error_status_ok
The call was successful
RELATED INFORMATION
Functions: sec_intro
sec_pwd_mgmt_setup
4.91 – sec_pwd_mgmt_gen_pwd
NAME
sec_pwd_mgmt_gen_pwd - Generate a set of passwords
SYNOPSIS
#include <dce/sec_pwd_mgmt.h>
void sec_pwd_mgmt_gen_pwd(
sec_pwd_mgmt_handle_t pwd_mgmt_h,
unsigned32 num_pwds,
unsigned32 *num_returned,
sec_passwd_rec_t gen_pwds[],
error_status_t *stp
)
PARAMETERS
Input
pwd_mgmt_h
A handle to user's password management data.
num_pwds
Number of generated passwords requested.
Output
num_returned
Number of generated passwords returned in the gen_pwds[] array.
gen_pwds
Array of generated passwords. Each generated password is stored
in a sec_passwd_rec_t structure.
stp A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_pwd_mgmt_gen_pwd() routine retrieves a set of generated
passwords from a password management server which is exporting the
rsec_pwd_mgmt_gen_pwd() routine. It obtains the binding information
to this server from the pwd_mgmt_h handle.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_PWD_MGMT.IDL
The idl file from which dce/sec_pwd_mgmt.h was derived.
ERRORS
sec_rgy_era_pwd_mgmt_auth_type
The pwd_mgmt_binding ERA must contain authentication
information.
sec_pwd_mgmt_svr_unavail
The password management server is unavailable
sec_pwd_mgmt_svr_error
Generic error returned from password management server.
An administrator should check the password management
server's log file for more information.
error_status_ok
The call was successful
Various RPC communication errors can be returned if there are failures
when binding to the password management server.
RELATED INFORMATION
Functions: sec_intro
sec_pwd_mgmt_setup
pwd_strengthd
4.92 – sec_pwd_mgmt_get_val_type
NAME
sec_pwd_mgmt_get_val_type - Gets users password validation type
SYNOPSIS
#include <dce/sec_pwd_mgmt.h>
void sec_pwd_mgmt_get_val_type(
sec_pwd_mgmt_handle_t pwd_mgmt_h,
signed32 *pwd_val_type,
error_status_t *stp
)
PARAMETERS
Input
pwd_mgmt_h
A handle to a user's password management data.
Output
pwd_val_type
The user's password validation type. This is retrieved from the
pwd_val_type ERA. The possible values and their meaning are:
(none): the user has no password policy.
(user_select): the user must choose his/her own password.
(user_can_select): the user can choose his/her own password
or request a generated password.
(generation_required): the user must use a generated password.
stp A pointer to the completion status. On successful completion,
stp is assigned error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_pwd_mgmt_get_val_type() routine returns the value of the
user's password validation type, as specified by the pwd_val_type ERA.
If the ERA does not exist, 0 (none) is returned in pwd_val_type.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_PWD_MGMT.IDL
The idl file from which dce/sec_pwd_mgmt.h was derived.
ERRORS
error_status_ok
The call was successful
Various RPC communication errors can be returned if there are failures
when binding to the password management server.
RELATED INFORMATION
Functions: sec_intro
sec_pwd_mgmt_setup
4.93 – sec_pwd_mgmt_setup
NAME
sec_pwd_mgmt_setup - Sets up the user's password policy information
SYNOPSIS
#include <dce/sec_pwd_mgmt.h>
void sec_pwd_mgmt_setup(
sec_pwd_mgmt_handle_t *pwd_mgmt_h,
sec_rgy_handle_t context,
sec_rgy_login_name_t login_name,
sec_login_handle_t your_lc,
rpc_binding_handle_t pwd_mgmt_bind_h,
error_status_t *stp
)
PARAMETERS
Input
context
A registry server handle indicating the desired registry site.
login_name
The login name of the user.
your_lc
The login context handle of the user currently logged in. If
null is specified, the default login context will be used.
pwd_mgmt_bind_h
An RPC binding handle to the password management server. Use of
this parameter is currently unsupported. The password management
server binding handle will be retrieved from the pwd_mgmt_binding
ERA. Set this parameter to NULL.
Output
pwd_mgmt_h
A pointer to an opaque handle to password management/policy data.
pwd_mgmt_h contains, among other data, the account name, values
of password management ERAs, and a binding handle to the password
management server.
stp A pointer to the completion status. On successful completion,
stp is assigned error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_pwd_mgmt_setup() routine collects the data required to perform
remote password management calls to the password management server.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_PWD_MGMT.IDL
The idl file from which dce/sec_pwd_mgmt.h was derived.
ERRORS
sec_s_no_memory
Not enough memory is available to complete the operation.
sec_rgy_server_unavailable
The network registry is not available.
error_status_ok
The call was successful
RELATED INFORMATION
Functions: sec_intro
sec_pwd_mgmt_free_handle
sec_pwd_mgmt_gen_pwd
sec_pwd_mgmt_get_val_type
pwd_strengthd
4.94 – sec_rgy_acct_add
NAME
sec_rgy_acct_add - Adds an account for a login name
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_add(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_key_t *key_parts,
sec_rgy_acct_user_t *user_part,
sec_rgy_acct_admin_t *admin_part,
sec_passwd_rec_t *caller_key,
sec_passwd_rec_t *new_key,
sec_passwd_type_t new_keytype,
sec_passwd_version_t *new_key_version,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
login_name
A pointer to the account login name. A login name is composed
of three character strings, containing the principal, group,
and organization (PGO) names corresponding to the account.
All three names must be completely specified.
key_parts
A pointer to the minimum abbreviation allowed when logging in
to the account. Abbreviations are not currently implemented and
the only legal value is sec_rgy_acct_key_person.
user_part
A pointer to the sec_rgy_acct_user_t structure containing the
user part of the account data. This represents such information
as the account password, home directory, and default shell.
admin_part
A pointer to the sec_rgy_acct_admin_t structure containing the
administrative part of an account's data. This information
includes the account creation and expiration dates and flags
describing limits to the use of privilege attribute certificates,
among other information.
caller_key
A key to use to encrypt new_key for transmission to the registry
server.
new_key
The password for the new account. During transmission to the
registry server, it is encrypted with caller_key.
new_keytype
The type of the new key. The server uses this parameter to decide
how to encode new_key if it is sent as plaintext.
Output
new_key_version
The key version number returned by the server. If the client
requests a particular key version number (via the version_number
field of the new_key input parameter), the server returns the
requested version number back to the client.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_add() routine adds an account with the specified
login name. The login name is given in three parts, corresponding to
the principal, group, and organization names for the account.
The key_parts variable specifies the minimum login abbreviation for
the account. If the requested abbreviation duplicates an existing
abbreviation for another account, the routine supplies the next
shortest unique abbreviation and returns this abbreviation in
key_parts. Abbreviations are not currently implemented.
Permissions Required
The sec_rgy_acct_add() routine requires the following permissions on the
account (principal) that is to be added:
+ The m (mgmt_info) permission to change management information.
+ The a (auth_info) permission to change authentication information.
+ The u (user_info) permission to change user information.
NOTES
The constituent principal, group, and organization (PGO) items for
an account must be added before the account can be created. (See the
sec_rgy_pgo_add() routine). Also, the principal must have been added
as a member of the specified group and organization. (See the
sec_rgy_pgo_add_member() routine).
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to add an account
to the registry.
sec_rgy_not_member_group
The indicated principal is not a member of the indicated
group.
sec_rgy_not_member_org
The indicated principal is not a member of the indicated
organization.
sec_rgy_not_member_group_org
The indicated principal is not a member of the indicated
group or organization.
sec_rgy_object exists
The account to be added already exists.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_delete
sec_rgy_login_get_info
sec_rgy_pgo_add
sec_rgy_pgo_add_member
sec_rgy_site_open
4.95 – sec_rgy_acct_admin_replace
NAME
sec_rgy_acct_admin_replace - Replaces administrative account data
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_admin_replace(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_key_t *key_parts,
sec_rgy_acct_admin_t *admin_part,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
login_name
A pointer to the account login name. A login name is composed
of three character strings, containing the principal, group,
and organization (PGO) names corresponding to the account.
For the group and organization names, blank strings can serve
as wildcards, matching any entry. The principal name must be
input.
key_parts
A pointer to the minimum abbreviation allowed when logging in
to the account. Abbreviations are not currently implemented
and the only legal value is sec_rgy_acct_key_person.
admin_part
A pointer to the sec_rgy_acct_admin_t structure containing the
administrative part of an account's data. This information
includes the account creation and expiration dates and flags
describing limits to the use of privilege attribute
certificates, among other information, and can be modified
only by an administrator. The sec_rgy_acct_admin_t structure
contains the following fields:
creator
The identity of the principal who created this account
in sec_rgy_foreign_id_t form. This field is set by the
registry server.
creation_date
The date (sec_timeval_sec_t) the account was created.
This field is set by the registry server.
last_changer
The identity of the principal who last modified any of
the account information (user or administrative). This
field is set by the registry server.
change_date
The date (sec_timeval_sec_t) the account was last
modified (either user or administrative data). This
field is set by the registry server.
expiration_date
The date (sec_timeval_sec_t) the account will cease
to be valid.
good_since_date
This date (sec_timeval_sec_t) is for Kerberos-style,
ticket-granting ticket revocation. Ticket-granting
tickets issued before this date will not be honored
by authenticated network services.
flags Contains administration flags used as part of the
administrator's information for any registry account.
This field is in sec_rgy_acct_admin_flags_t form.
(See sec_intro for a complete description of these
flags.)
authentication_flags
Contains flags controlling use of authentication
services. This field is in sec_rgy_acct_auth_flags_t
form. (See sec_intro for a complete description of
these flags.)
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_admin_replace() routine replaces the administrative
information in the account record specified by the input login name.
The administrative information contains limitations on the account's
use and privileges. It can be modified only by a registry
administrator; that is, a user with the admin_info (abbreviated as a)
privilege for an account.
The key_parts variable identifies how many of the login_name parts to
use as the unique abbreviation for the account. If the requested
abbreviation duplicates an existing abbreviation for another account,
the routine supplies the next shortest unique abbreviation and returns
this abbreviation using key_parts.
Permissions Required
The sec_rgy_acct_admin_replace() routine requires the following
permissions on the account principal:
+ The m (mgmt_info) permission, if flags or expiration_date is to be
changed.
+ The a (auth_info) permission, if authentication_flags or
good_since_date is to be changed.
NOTES
All users need the w (write) privilege in the appropriate ACL entry to
modify any account information.
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to change the
administrative information for the specified account.
sec_rgy_object_not_found
The registry server could not find the specified name.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_user_replace
sec_rgy_acct_replace_all
sec_rgy_acct_lookup
4.96 – sec_rgy_acct_delete
NAME
sec_rgy_acct_delete - Deletes an account
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_delete(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
error_status_t *status);
PARAMETERS
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
login_name
A pointer to the account login name. A login name is composed
of three character strings, containing the principal, group,
and organization (PGO) names corresponding to the account.
Only the principal name is required to perform the deletion.
Output
status A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_delete() routine deletes from the registry the account
corresponding to the specified login name.
Permissions Required
The sec_rgy_acct_delete() routine requires the following permissions
on the account principal:
+ The m (mgmt_info) permission to remove management information.
+ The a (auth_info) permission to remove authentication information.
+ The u (user_info) permission to remove user information.
NOTES
Even though the account is deleted, the PGO items corresponding to the
account remain. These must be deleted with separate calls to
sec_rgy_pgo_delete().
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to delete the
specified account.
sec_rgy_object_not_found
No PGO item was found with the given name.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_add
sec_rgy_pgo_delete
4.97 – sec_rgy_acct_get_projlist
NAME
sec_rgy_acct_get_projlist - Returns the projects in an account's
project list
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_get_projlist(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_cursor_t *projlist_cursor,
signed32 max_number,
signed32 *supplied_number,
uuid_t id_projlist[],
signed32 unix_projlist[],
signed32 *num_projects,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
login_name
A pointer to the account login name. A login name is composed
of three character strings, containing the principal, group, and
organization (PGO) names corresponding to the account. For the
group and organization names, blank strings can serve as
wildcards, matching any entry. The principal name must be input.
max_number
The maximum number of projects to be returned by the call. This
must be no larger than the allocated size of the projlist[]
arrays.
Input/Output
projlist_cursor
An opaque pointer indicating a specific project in an account's
project list. The sec_rgy_acct_get_projlist() routine returns the
project indicated by projlist_cursor, and advances the cursor to
point to the next project in the list. When the end of the list
is reached, the routine returns the value sec_rgy_no_more_entries
in the status parameter. Use sec_rgy_cursor_reset() to reset the
cursor.
Output
supplied_number
A pointer to the actual number of projects returned. This will
always be less than or equal to the max_number supplied on input.
If there are more projects in the account list,
sec_rgy_acct_get_projlist() sets projlist_cursor to point to the
next entry after the last one in the returned list.
id_projlist[]
An array to receive the UUID of each project returned. The size
allocated for the array is given by max_number. If this value
is less than the total number of projects in the account project
list, multiple calls must be made to return all of the projects.
unix_projlist[]
An array to receive the UNIX number of each project returned.
The size allocated for the array is given by max_number. If
this value is less than the total number of projects in the
account project list, multiple calls must be made to return all
of the projects.
num_projects
A pointer indicating the total number of projects in the
specified account's project list.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_get_projlist() routine returns members of the project
list for the specified account. It returns the project information in
two arrays. The id_projlist[] array contains the UUIDs for the returned
projects. The unix_projlist[] array contains the UNIX numbers for the
returned projects.
The project list cursor, projlist_cursor, provides an automatic place
holder in the project list. The sec_rgy_acct_get_projlist() routine
automatically updates this variable to point to the next project in the
project list. To return an entire project list, reset projlist_cursor
with sec_rgy_cursor_reset() on the initial call and then issue
successive calls until all the projects are returned.
Permissions Required
The sec_rgy_acct_get_projlist() routine requires the r (read)
permission on the account principal for which the project list data
is to be returned.
CAUTIONS
There are several different types of cursors used in the registry
Application Programmer Interface (API). Some cursors point to PGO
items, others point to members in a membership list, and others point
to account data. Do not use a cursor for one sort of object in a call
expecting another sort of object. For example, you cannot use the same
cursor on a call to sec_rgy_acct_get_projlist() and
sec_rgy_pgo_get_next(). The behavior in this case is undefined.
Furthermore, cursors are specific to a server. A cursor pointing into
one replica of the registry database is useless as a pointer into
another replica.
Use sec_rgy_cursor_reset() to refresh a cursor for use with another call
or for another server.
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_no_more_entries
The cursor is at the end of the list of projects.
sec_rgy_not_authorized
The client program is not authorized to see a project list
for this principal.
sec_rgy_object exists
The account to be added already exists.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_cursor_reset
sec_rgy_pgo_get_next
4.98 – sec_rgy_acct_lookup
NAME
sec_rgy_acct_lookup - Returns data for a specified account
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_lookup(
sec_rgy_handle_t context,
sec_rgy_login_name_t *name_key,
sec_rgy_cursor_t *account_cursor,
sec_rgy_login_name_t *name_result,
sec_rgy_sid_t *id_sid,
sec_rgy_unix_sid_t *unix_sid,
sec_rgy_acct_key_t *key_parts,
sec_rgy_acct_user_t *user_part,
sec_rgy_acct_admin_t *admin_part,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_key
A pointer to the account login name. A login name is composed
of three character strings, containing the principal, group,
and organization (PGO) names corresponding to the account.
Blank strings serve as wildcards, matching any entry.
Input/Output
account_cursor
An opaque pointer to a specific account in the registry database.
If name_key is blank, sec_rgy_acct_lookup() returns information
about the account to which the cursor is pointing. On return,
the cursor points to the next account in the database after the
returned account. If name_key is blank and the account_cursor
has been reset with sec_rgy_cursor_reset(),
sec_rgy_acct_lookup() returns information about the first
account in the database. When the end of the list of accounts
in the database is reached, the routine returns the value
sec_rgy_no_more_entries in the status parameter. Use
sec_rgy_cursor_reset() to refresh the cursor.
Output
name_result
A pointer to the full login name of the account (including all
three names) for which the information is returned. The
remaining parameters contain the information belonging to the
returned account.
id_sid
A structure containing the three UUIDs of the principal, group,
and organization for the account.
unix_sid
A structure containing the three UNIX numbers of the principal,
group, and organization for the account.
key_parts
A pointer to the minimum abbreviation allowed when logging in
to the account. Abbreviations are not currently implemented
and the only legal value is sec_rgy_acct_key_person.
user_part
A pointer to the sec_rgy_acct_user_t structure containing the
user part of the account data. This represents such information
as the account password, home directory, and default shell, all
of which are accessible to, and may be modified by, the account
owner.
admin_part
A pointer to the sec_rgy_acct_admin_t structure containing the
administrative part of an account's data. This information
includes the account creation and expiration dates and flags
describing limits to the use of privilege attribute
certificates, among other information, and can be modified
only by an administrator.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_lookup() routine returns all the information about
an account in the registry database. The account can be specified
either with name_key or account_cursor. If name_key is completely
blank, the routine uses the account_cursor value instead.
For name_key, a zero-length principal, group, or organization key
serves as a wildcard. For example, a login name key with the
principal and organization fields blank returns the next (possibly
first) account whose group matches the input group field. The full
login name of the returned account is passed back in name_result.
The account_cursor provides an automatic place holder in the registry
database. The routine automatically updates this variable to point to
the next account in the database, after the account for which the
information was returned. If name_key is blank and the account_cursor
has been reset with sec_rgy_cursor_reset()*O, sec_rgy_acct_lookup()
returns information about the first account in the database.
Permissions Required
The sec_rgy_acct_lookup() routine requires the r (read) permission
on the account principal to be viewed.
CAUTIONS
There are several different types of cursors used in the registry
Application Programmer Interface (API). Some cursors point to PGO
items, others point to members in a membership list, and others point
to account data. Do not use a cursor for one sort of object in a call
expecting another sort of object. For example, you cannot use the
same cursor on a call to sec_rgy_acct_get_projlist() and
sec_rgy_pgo_get_next(). The behavior in this case is undefined.
Furthermore, cursors are specific to a server. A cursor pointing into
one replica of the registry database is useless as a pointer into
another replica.
Use sec_rgy_cursor_reset() to renew a cursor for use with another call
or for another server.
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_no_more_entries
The cursor is at the end of the accounts in the registry.
sec_rgy_object_not_found
The input account could not be found by the registry
server.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_cursor_reset
sec_rgy_acct_replace_all
sec_rgy_acct_admin_replace
sec_rgy_acct_user_replace
4.99 – sec_rgy_acct_passwd
NAME
sec_rgy_acct_passwd - Changes the password for an account
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_passwd(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_passwd_rec_t *caller_key,
sec_passwd_rec_t *new_key,
sec_passwd_type_t new_keytype,
sec_passwd_version_t *new_key_version,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
login_name
A pointer to the account login name. A login name is composed
of three character strings, containing the principal, group,
and organization (PGO) names corresponding to the account.
All three strings must be completely specified.
caller_key
A key to use to encrypt the key for transmission to the registry
server. If communications secure to the
rpc_c_authn_level_pkt_privacy level are available on a system,
then this parameter is not necessary, and the packet encryption
is sufficient to ensure security.
new_key
The password for the new account. During transmission to the
registry server, it is encrypted with caller_key.
new_keytype
The type of the new key. The server uses this parameter to decide
how to encode new_key if it is sent as plaintext.
Output
new_key_version
The key version number returned by the server. If the client
requests a particular key version number (via the version_number
field of the new_key input parameter), the server returns the
requested version number back to the client.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_passwd() routine changes an account password to the
input password character string. Wildcards (blank fields) are not
permitted in the specified account name; the principal, group, and
organization names of the account must be completely specified.
Permissions Required
The sec_rgy_acct_passwd() routine requires the u (user_info)
permission on the account principal whose password is to be changed.
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to change the
password of this account.
sec_rgy_object_not_found
The account to be modified was not found by the registry
server.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
4.100 – sec_rgy_acct_rename
NAME
sec_rgy_acct_rename - Changes an account login name
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_rename(
sec_rgy_handle_t context,
sec_rgy_login_name_t *old_login_name,
sec_rgy_login_name_t *new_login_name,
sec_rgy_acct_key_t *new_key_parts,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
old_login_name
A pointer to the current account login name. The login name is
composed of three character strings, containing the principal,
group, and organization (PGO) names corresponding to the
account. All three strings must be completely specified.
new_login_name
A pointer to the new account login name. Again, all three
component names must be completely specified.
Input/Output
new_key_parts
A pointer to the minimum abbreviation allowed when logging in
to the account. Abbreviations are not currently implemented and
the only legal value is sec_rgy_acct_key_person.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_rename() routine changes an account login name from
old_login_name to new_login_name. Wildcards (empty fields) are not
permitted in either input name; both the old and new login names must
completely specify their component principal, group, and organization
names. Note, though, that the principal component in a login name
cannot be changed.
The new_key_parts variable identifies how many of the new_login_name
parts to use as the unique abbreviation for the account. If the
requested abbreviation duplicates an existing abbreviation for another
account, the routine identifies the next shortest unique abbreviation
and returns this abbreviation using new_key_parts.
Permissions Required
The sec_rgy_acct_rename() routine requires the m (mgmt_info)
permission on the account principal to be renamed.
NOTES
The sec_rgy_acct_rename() routine does not affect any of the registry
PGO data. The constituent principal, group, and organization items
for an account must be added before the account can be created.
(See the sec_rgy_pgo_add routine). Also, the principal must have
been added as a member of the specified group and organization.
(See the sec_rgy_pgo_add_member routine).
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to make the changes.
sec_rgy_object_not_found
The account to be modified was not found by the registry
server.
sec_rgy_name_exists
The new account name is already in use by another account.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_add
4.101 – sec_rgy_acct_replace_all
NAME
sec_rgy_acct_replace_all - Replaces all account data for an account
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_replace_all(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_key_t *key_parts,
sec_rgy_acct_user_t *user_part,
sec_rgy_acct_admin_t *admin_part,
boolean32 set_password,
sec_passwd_rec_t *caller_key,
sec_passwd_rec_t *new_key,
sec_passwd_type_t new_keytype,
sec_passwd_version_t *new_key_version,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
login_name
A pointer to the account login name. A login name is composed
of three character strings, containing the principal, group,
and organization (PGO) names corresponding to the account. For
the group and organization names, blank strings can serve as
wildcards, matching any entry. The principal name must be input.
user_part
A pointer to the sec_rgy_acct_user_t structure containing the
user part of the account data. This represents such information
as the account password, home directory, and default shell, all
of which are accessible to, and may be modified by, the account
owner.
admin_part
A pointer to the sec_rgy_acct_admin_t structure containing the
administrative part of an account's data. This information
includes the account creation and expiration dates and flags
describing limits to the use of privilege attribute
certificates, among other information, and can be modified only
by an administrator.
set_passwd
The password reset flag. If you set this parameter to TRUE, the
account's password will be changed to the value specified in
new_key.
caller_key
A key to use to encrypt the key for transmission to the registry
server. If communications secure to the
rpc_c_authn_level_pkt_privacy level are available on a system,
then this parameter is not necessary, and the packet encryption
is sufficient to ensure security.
new_key
The password for the new account. During transmission to the
registry server, it is encrypted with caller_key.
new_keytype
The type of the new key. The server uses this parameter to
decide how to encode the plaintext key.
Input/Output
key_parts
A pointer to the minimum abbreviation allowed when logging in
to the account. Abbreviations are not currently implemented
and the only legal value is sec_rgy_acct_key_person.
Output
new_key_version
The key version number returned by the server. If the client
requests a particular key version number (via the version_number
field of the new_key input parameter), the server returns the
requested version number back to the client.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_replace_all() routine replaces both the user and
administrative information in the account record specified by the
input login name. The administrative information contains limitations
on the account's use and privileges. The user information contains
such information as the account home directory and default shell.
Typically, the administrative information can only be modified by a
registry administrator (users with admin_info (a) privileges for an
account), while the user information can be modified by the account
owner (users with user_info (u) privileges for an account).
Use the set_passwd parameter to reset the account password. If you set
this parameter to TRUE, the account's pasword is changed to the value
specified in new_key.
The key_parts variable identifies how many of the login_name parts to
use as the unique abbreviation for the replaced account. If the
requested abbreviation duplicates an existing abbreviation for another
account, the routine identifies the next shortest unique abbreviation
and returns this abbreviation using key_parts.
Permissions Required
The sec_rgy_acct_replace_all() routine requires the following
permissions on the account principal:
+ The m (mgmt_info) permission, if flags or expiration_date is to
be changed.
+ The a (auth_info) permission, if authentication_flags or
good_since_date is to be changed.
+ The u (user_info) permission, if user flags, gecos, homedir (home
directory), shell, or passwd (password) are to be changed.
NOTES
All users need the w (write) privilege to modify any account
information.
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to change account
information.
sec_rgy_object_not_found
The specified account could not be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_add
sec_rgy_acct_admin_replace
sec_rgy_acct_rename
sec_rgy_acct_user_replace
4.102 – sec_rgy_acct_user_replace
NAME
sec_rgy_acct_user_replace - Replaces user account data
SYNOPSIS
#include <dce/acct.h>
void sec_rgy_acct_user_replace(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_user_t *user_part,
boolean32 set_passwd,
sec_passwd_rec_t *caller_key,
sec_passwd_rec_t *new_key,
sec_passwd_type_t new_keytype,
sec_passwd_version_t *new_key_version,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
login_name
A pointer to the account login name. A login name is composed
of three character strings, containing the principal, group,
and organization (PGO) names corresponding to the account.
For the group and organization names, blank strings can serve
as wildcards, matching any entry. The principal name must be
input.
user_part
A pointer to the sec_rgy_acct_user_t structure containing the
user part of the account data. This represents such information
as the account password, home directory, and default shell, all
of which are accessible to, and may be modified by, the account
owner. The structure contains the following fields:
gecos
A character string containing information about the
account owner. This often includes such information as
their name and telephone number.
homedir
The default directory upon login for the account.
shell The default shell to use upon login.
passwd_version_number
The password version number, a 32-bit unsigned integer,
set by the registry server.
passwd_dtm
The date and time of the last password change (in
sec_timeval_sec_t form), also set by the registry server.
flags A flag set of type sec_rgy_acct_user_flags_t.
passwd
The account's encrypted password.
set_passwd
The password reset flag. If you set this parameter to TRUE,
the user's password will be changed to the value specified
in new_key.
caller_key
A key to use to encrypt the key for transmission to the
registry server. If communications secure to the
rpc_c_authn_level_pkt_privacy level are available on a system,
then this parameter is not necessary, and the packet
encryption is sufficient to ensure security.
new_key
The password for the new account. During transmission to the
registry server, it is encrypted with caller_key.
new_keytype
The type of the new key. The server uses this parameter to
decide how to encode the plaintext key.
Output
new_key_version
The key version number returned by the server. If the client
requests a particular key version number (via the version_number
field of the new_key input parameter), the server returns the
requested version number back to the client.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_acct_user_replace() routine replaces the user information
in the account record specified by the input login name. The user
information contains such information as the account home directory
and default shell. Typically, the the user information can be
modified by the account owner (users with user_info (u) privileges
for an account).
Use the set_passwd parameter to reset the user's password. If you set
this parameter to TRUE, the user's pasword is changed to the value
specified in new_key.
Permissions Required
The sec_rgy_acct_user_replace() routine requires the u (user_info)
permission on the account principal.
NOTES
All users need the w (write) privilege to modify any account
information.
FILES
SYS$COMMON:[DCE$LIBRARY]ACCT.IDL
The idl file from which dce/acct.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to modify the
account data.
sec_rgy_object_not_found
The specified account could not be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_add
sec_rgy_acct_admin_replace
sec_rgy_acct_rename
sec_rgy_acct_replace_all
4.103 – sec_rgy_attr_cursor_alloc
NAME
sec_rgy_attr_cursor_alloc - Allocates resources to a cursor used by
the sec_rgy_attr_lookup_by_id call
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_cursor_alloc(
sec_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Output
cursor A pointer to a sec_attr_cursor_t.
status
A pointer to the completion status. On successful completion,
the call returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_cursor_alloc() call allocates resources to a cursor
used with the sec_rgy_attr_lookup_by_id call. This routine, which is
a local operation, does not initialize cursor.
The sec_rgy_attr_cursor_init() routine, which makes a remote call,
allocates and initializes the cursor. In addition,
sec_rgy_attr_cursor_init() returns the total number of attributes
attached to the object as an output parameter;
sec_rgy_attr_cursor_alloc() does not.
Permissions Required
None
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_ATTR_BASE.IDL
The idl file from which dce/sec_attr_base.h was derived.
ERRORS
no such object
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_cursor_init
sec_rgy_attr_cursor_release
sec_rgy_attr_cursor_reset
sec_rgy_attr_lookup_by_id
4.104 – sec_rgy_attr_cursor_init
NAME
sec_rgy_attr_cursor_init - Initialize a cursor used by the
sec_rgy_attr_lookup_by_id call
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_cursor_init (
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
unsigned32 *cur_num_attrs,
sec_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
A value of type sec_rgy_domain_t that identifies the registry
domain in which the object specified by name resides. The valid
values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
This parameter is ignored if name is policy or replist.
name A pointer to a sec_rgy_name_t character string containing the
name of the person, group, or organization to which the
attribute to be scanned is attached.
Output
cur_num_attrs
A pointer to an unsigned 32-bit integer that specifies the
number of attributes currently attached to the object.
cursor
A pointer to a sec_rgy_cursor_t positioned at the first
attribute in the list of the object's attributes.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_cursor_init() routine initializes a cursor of type
sec_attr_cursor_t (used with the sec_rgy_attr_lookup_by_id call) and
initializes the cursor to the first attribute in the specified object's
list of attributes. This call also supplies the total number of
attributes attached to the object as part of its output. The cursor
allocation is a local operation. The cursor initialization is a remote
operation and makes a remote call to the Registry.
Use the sec_rgy_attr_cursor_release() call to release all resources
allocated to a sec_attr_cursor_t cursor.
Permissions Required
The sec_rgy_attr_cursor_init() routine requires at least one permission
(of any type) on the person, group, or organization to which the
attribute to be scanned is attached.
ERRORS
no such object
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_lookup_by_id
sec_rgy_attr_cursor_release
4.105 – sec_rgy_attr_cursor_release
NAME
sec_rgy_attr_cursor_release - Release a cursor of
typesec_attr_cursor_t that was
allocated with the
sec_rgy_attr_cursor_init() or
sec_rgy_attr_cursor_alloc() call
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_cursor_release (
sec_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
Input/Output
*cursor
As an input parameter, a pointer to an uninitialized cursor of
type sec_attr_cursor_t. As an output parameter, a pointer to an
uninitialized cursor of type sec_attr_cursor_t with all resources
released.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_cursor_release() routine releases all resources
allocated to a sec_attr_cursor_t by the sec_rgy_attr_cursor_init()
or sec_rgy_attr_cursor_alloc() call.
This is a local-only operation and makes not remote calls.
Permissions Required
None.
ERRORS
No such object
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_cursor_init
sec_rgy_attr_cursor_alloc
sec_rgy_attr_lookup_by_id
4.106 – sec_rgy_attr_cursor_reset
NAME
sec_rgy_attr_cursor_reset - Rinitializes a cursor that has
been allocated with either
sec_rgy_attr_cursor_init() or
sec_rgy_attr_cursor_alloc().
SYNOPSIS
#include <dce/sec_attr_base.h>
void sec_attr_cursor_reset(
sec_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input/Output
cursor
A pointer to a sec_attr_cursor_t. As an input parameter, an
initialized cursor. As an output parameter, cursor is reset to
the first attribute in the schema.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_cursor_reset() routine resets a dce_attr_cursor_t
that has been allocated by either a sec_rgy_attr_cursor_init() or
sec_rgy_attr_cursor_alloc(). The reset cursor can then be used to
process a new sec_rgy_attr_lookup_by_id query by reusing the cursor
instead of releasing and re-allocating it. This is a local operation
and makes no remote calls.
Permissions Required
None.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL
The idl file from which dce/sec_rgy_attr.h was derived.
ERRORS
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_cursor_init
sec_rgy_attr_cursor_alloc
sec_rgy_attr_lookup_by_id
4.107 – sec_rgy_attr_delete
NAME
sec_rgy_attr_delete - Deletes specified attributes for a specified
object
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_delete (
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
unsigned32 num_to_delete,
sec_attr_t attrs[],
signed32 *failure_index,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
A value of type sec_rgy_domain_t that identifies the registry
domain in which the object identified by name resides. The valid
values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
This parameter is ignored if name is policy or replist.
name A character string of type sec_rgy_name_t specifying the name
of the person, group, or organization to which the attributes
are attached.
num_to_delete
A 32-bit integer that specifies the number of elements in the
attrs[] array. This integer must be greater than 0.
attrs[]
An array of values of type sec_attr_t that specifies the
attribute instances to be deleted. The size of the array is
determined by num_to_delete.
Output
failure_index
In the event of an error, failure_index is a pointer to the
element in the in_attrs[] array that caused the update to fail.
If the failure cannot be attributed to a specific attribute, the
value of failure_index is -1.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_delete() routine deletes attributes. This is an atomic
operation: if the deletion of any attribute in the attrs[] array fails,
all deletions are aborted. The attribute causing the delete to fail is
identified in failure_index. If the failure cannot be attributed to a
given attribute, failure_index contains -1.
The attrs array, which specifies the attributes to be deleted, contains
values of type sec_attr_t These values consist of:
+ attr_id, a UUID that identifies the attribute type
+ attr_value, values of sec_attr_value_t that specify the
attribute's encoding type and values.
To delete attributes that are not multi-valued and to delete all
instances of a multi-valued attribute, an attribute UUID is all that
is required. For these attribute instances, supply the attribute
UUID in the input array and set the attribute encoding (in
sec_attr_encoding_t) to sec_attr_enc_void.
To delete a specific instance of a multi-valued attribute, supply the
UUID and value that uniquely identify the multi-valued attribute
instance in the input array.
Note that if the deletion of any attribute instance in the array fails,
all fail. However, to help pinpoint the cause of the failure, the call
identifies the first attribute whose deletion failed in a failure index
by array element number.
Permissions Required
The sec_rgy_attr_delete() routine requires the delete permission set
for each attribute type identified in the attrs[] array. These
permissions are defined as part of the ACL manager set in the schema
entry for the attribute type.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL
The idl file from which dce/sec_rgy_attr.h was derived.
ERRORS
unauthorized
database read only
server unavailable
invalid/unsupported attribute type
site read only
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_update
4.108 – sec_rgy_attr_get_effective
NAME
sec_rgy_attr_get_effective - Reads effective attributes by ID
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_get_effective(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
unsigned32 num_attr_keys,
sec_attr_t attr_keys[],
sec_attr_vec_t *attr_list,
error_status_t status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
A value of type sec_rgy_domain_t that identifies the domain in
which the named object resides. The valid values are as follows:
sec_rgy_domain_principal
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
This parameter is ignored if name is policy or replist.
name A pointer to a sec_rgy_name_t character string containing the
name of the person, group, or organization to which the
attribute is attached.
num_attr_keys
An unsigned 32-bit integer that specifies the number of elements
in the the attr_keys[] array. If num_attr_keys is set to 0,
all of the effective attributes that the caller is authorized to
see are returned.
attr_keys[]
An array of values of type sec_attr_t that specify the UUIDs
of the attributes to be returned if they are effective. If the
attribute type is associated with a query attribute trigger,
the sec_attr_t attr_value field can be used to pass in optional
information required by the attribute trigger query. If no
information is to be passed in the attr_value field (whether
the type indicates an attribute trigger query or not), set the
attribute's encoding type to sec_rgy_attr_enc_void. The size
of the attr_keys[] array is determined by the num_attr_keys
parameter.
Output
attr_list
A pointer an attribute vector allocated by the server containing
all of the effective attributes matching the search criteria
(defined in num_attr_keys or attr_keys[] ). The server
allocates a buffer large enough to return all the requested
attributes so that subsequent calls are not necessary.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_get_effective() routine returns the UUIDs of a
pecified object's effective attributes. Effective attributes are
determined by setting of the schema entry apply_defaults flag:
+ If the flag is set off, only the attributes directly attached
to the object are effective.
+ If the flag is set on, the effective attributes are obtained by
performing the following steps for each attribute identified by
UUID in the attr_keys array:
1. If the object named by name is a principal and if the a
requested attribute exists on the principal, that attribute
is effective and is returned. If it does not exist, the
search continues.
2. The next step in the search depends on the type of object:
For principals with accounts:
a. The organization named in the principal's account is
examined to see if an attribute of the requested type
exists. If it does, it is effective and is returned;
then the search for that attribute ends. If it does
not exist, the search for that attribute continues to
the policy object as described in b, below.
b. The registry policy object is examined to see if an
attribute of the requested type exits. If it does, it
is returned. If it does not, a message indicating the
no attribute of the type exists for the object is
returned.
For principals without accounts, for groups, and for organizations:
the registry policy object is examined to see if an attribute of
the requested type exits. If it does, it is returned. If it does
not, a message indicating the no attribute of the type exists for
the object is returned.
For multi-valued attributes, the call returns a sec_attr_t for each
value as an individual attribute instance. For attribute sets, the
call returns a sec_attr_t for each member of the set; it does not
return the set instance.
If the attribute instance to be read is associated with a query
attribute trigger that requires additional information before it
can process the query request, use a sec_attr_value_t to supply the
requested information. To do this:
+ Set the sec_attr_encoding_t to an encoding type that is compatible
with the information required by the query attribute trigger.
+ Set the sec_attr_value_t to hold the required information.
If the attribute instance to be read is not associated with a query
trigger or no additional information is required by the query trigger,
an attribute UUID is all that is required. For these attribute
instances, supply the attribute UUID in the input array and set the
attribute encoding (in sec_attr_encoding_t) to sec_attr_enc_void.
If the requested attribute type is associated with a query trigger,
the value returned for the attribute will be the binding (as set in
the schema entry) of the trigger server. The caller must bind to the
trigger server and pass the original input query attribute to the
sec_attr_trig_query call in order to retrieve the attribute value.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL
The idl file from which dce/sec_rgy_attr.h was derived.
ERRORS
error_status_ok
RELATED INFORMATION
Functions: sec_intro
4.109 – sec_rgy_attr_lookup_by_id
NAME
sec_rgy_attr_lookup_by_id - Reads a specified object's attribute(s),
expanding attribute sets into individual
member attributes
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_lookup_by_id (
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
sec_attr_cursor_t *cursor,
unsigned32 num_attr_keys,
unsigned32 space_avail,
sec_attr_t attr_keys[],
unsigned32 *num_returned,
sec_attr_t attrs[],
unsigned32 *num_left,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
A value of type sec_rgy_domain_t that identifies the registry
domain in which the object specified by name resides. The valid
values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
This parameter is ignored if name is policy or replist.
name A pointer to a sec_rgy_name_t character string containing the
name of the person, group, or organization to which the
attribute is attached.
num_attr_keys
An unsigned 32-bit integer that specifies the number of elements
in the attr_keys array. Set this parameter to 0 to return all
of the object's attributes that the caller is authorized to see.
space_avail
An unsigned 32-bit integer that specifies the size of the
attr_keys array.
attr_keys[]
An array of values of type sec_attr_t that identify the attribute
type ID of the attribute instance(s) to be looked up. If the
attribute type is associated with a query attribute trigger,
the sec_attr_t attr_value field can be used to pass in optional
information required by the attribute trigger query. If no
information is to be passed in the attr_value field (whether
the type indicates an attribute trigger query or not), set the
attribute's encoding type to sec_rgy_attr_enc_void. The size
of the attr_keys[] array is determined by the num_attr_keys
parameter.
Input/Output
cursor
A pointer to a sec_attr_cursor_t. As an input parameter, cursor
is a pointer to a sec_attr_cursor_t initialized by a
sec_rgy_attr_srch_cursor_init call. As an output parameter,
cursor is a pointer to a sec_attr_cursor_t that is positioned
past components returned in this call.
Output
num_returned
A pointer to a 32-bit unsigned integer that specifies the number
of attribute instances returned in the attrs[] array.
attrs An array of values of type sec_attr_t that contains the
attributes retrieved by UUID. The size of the array is
determined by space_avail and the length by num_returned.
num_left
A pointer to a 32-bit unsigned integer that supplies the number
of attributes that were found but could not be returned because
of space constraints in the attrs[] buffer. To ensure that all
the attributes will be returned, increase the size of the
attrs[] array by increasing the size of space_avail and
num_returned.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok, or, if the requested
attributes were not available, it returns the message
not_all_available. Otherwise, it returns an error.
DESCRIPTION
The sec_rgy_attr_lookup_by_id() function reads those attributes
specified by UUID for an object specified by name. This routine is
similar to the sec_rgy_attr_lookup_no_expand routine with one
exception: for attribute sets, the sec_rgy_attr_lookup_no_expand
routine returns a sec_attr_t for the set instance only; it does not
expand the set and return a sec_attr_t for each member in the set.
This call expands attribute sets and returns a sec_attr_t for each
member in the set.
If the num_attr_keys parameter is set to 0, all of the object's
attributes that the caller is authorized to see are returned. This
routine is useful for programmatic access.
For multi-valued attributes, the call returns a sec_attr_t for each
value as an individual attribute instance. For attribute sets, the call
returns a sec_attr_t for each member of the set; it does not return
the set instance.
The attr_keys[] array, which specifies the attributes to be returned,
contains values of type sec_attr_t. These values consist of:
+ attr_id, a UUID that identifies the attribute type
+ attr_value, values of sec_attr_value_t that specify the attribute's
encoding type and values.
Use the attr_id field of each attr_keys array element, to specify the
UUID that identifies the attribute type to be returned.
If the attribute instance to be read is not associated with a query
trigger or no additional information is required by the query trigger,
an attribute UUID is all that is required. For these attribute
instances, supply the attribute UUID in the input array and set the
attribute encoding (in sec_attr_encoding_t) to sec_attr_enc_void.
If the attribute instance to be read is associated with a query
attribute trigger that requires additional information before it
can process the query request, use a sec_attr_value_t to supply the
requested information.
To do this:
+ Set the sec_attr_encoding_t to an encoding type that is compatible
with the information required by the query attribute trigger.
+ Set the sec_attr_value_t to hold the required information.
Note that if you set num_attr_keys to zero to return all of the object's
attributes and that attribute is associated with a query attribute
trigger, the attribute trigger will be called with no input attribute
information (that would normally have been passed in via the attr_value
field).
The cursor parameter specifies a cursor of type sec_attr_cursor_t
initialized to the point in the attribute list at which to start
processing the query. Use the sec_attr_cursor_init function to
initialize cursor. If cursor is uninitialized, the server begins
processing the query at the first attribute that satisfies the search
criteria.
The num_left parameter contains the number of attributes that were
found but could not be returned because of space constraints of the
attrs[] array. (Note that this number may be inaccurate if the target
server allows updates between successive queries.) To obtain all of the
remaining attributes, set the size of the attrs[] array so that it is
large enough to hold the number of attributes listed in num_left.
Permissions Required
The sec_rgy_attr_lookup_by_id() routine requires the query permission
set for each attribute type identified in the attr_keys[] array. These
permissions are defined as part of the ACL manager set in the schema
entry of each attribute type.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL
The idl file from which dce/sec_rgy_attr.h was derived.
ERRORS
unauthorized
registry server unavailable
trigger server unavailable
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_lookup_no_expand
sec_rgy_attr_attr_lookup_by_name
4.110 – sec_rgy_attr_lookup_by_name
NAME
sec_rgy_attr_lookup_by_name - Read a single attribute instance for a
specific object
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_lookup_by_name(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
char *attr_name,
sec_attr_t *attr,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
A value of type sec_rgy_domain_t that identifies the domain in
which the named object resides. The valid values are as follows:
sec_rgy_domain_principal
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
This parameter is ignored if name is policy or replist.
name A pointer to a sec_rgy_name_t character string containing
the name of the person, group, or organization to which the
attribute is attached.
attr_name
An pointer to a character string that specifies the name of the
attribute to be retrieved.
Output
attr A pointer to a sec_attr_t that contains the first instance
of the named attribute.
status
A pointer to the completion status. The completion status can
be one of the following:
+ error_status_ok if all instances of the value are returned
with no errors.
+ more_available if a multi-valued attribute was specified
as name and the routine completed successfully. For multi-
valued attributes, this routine returns the first instance
of the attribute.
+ attribute_set_instance if an attribute set was specified
as name and the routine completed successfully.
+ An error message is the routine did not complete
successfully.
DESCRIPTION
The sec_rgy_attr_lookup_by_name() routine returns the named attribute
for a named object. This routine is useful for an interactive editor.
For multi-valued attributes, this routine returns the first instance
of the attribute. To retrieve every instance of the attribute, use the
sec_rgy_attr_lookup_by_id call, supplying the attribute UUID returned
in the attr parameter.
For attribute sets, the routine returns the attribute set instance,
not the member instances. To retrieve all members of the set, use the
sec_rgy_attr_lookup_by_id call, supplying the the attribute set UUID
returned in the attr parameter.
Warning
This routine does not provide for input data to an attribute trigger
query operation. If the named attribute is associated with a query
attribute trigger, the attribute trigger will be called with no input
attribute value information.
Permissions Required
The sec_rgy_attr_lookup_by_name() routine requires the query permission
set for the attribute type of the attribute instance identified by
attr_name. These permissions are defined as part of the ACL manager
set in the schema entry of each attribute type
ERRORS
unauthorized
registry server unavailable
trigger server unavailable
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_lookup_by_id
sec_rgy_attr_lookup_no_expand
4.111 – sec_rgy_attr_lookup_no_expand
NAME
sec_rgy_attr_lookup_no_expand - Reads a specified object's
attribute(s), without expanding
attribute sets into individual
member attributes
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_lookup_no_expand(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
sec_attr_cursor_t *cursor,
unsigned32 num_attr_keys,
unsigned32 space_avail,
uuid_t attr_keys[],
unsigned32 *num_returned,
sec_attr_t attr_sets[],
unsigned32 *num_left,
error_status_t status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
A value of type sec_rgy_domain_t that identifies the domain
in which the named object resides. The valid values are as
follows:
sec_rgy_domain_principal
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
This parameter is ignored if name is policy or replist.
name A pointer to a sec_rgy_name_t character string containing the
name of the person, group, or organization to which the
attribute is attached.
num_attr_keys
An unsigned 32-bit integer that specifies the number of elements
in the the attr_keys[] array. If num_attr_keys is set to 0, all
attribute sets that the caller is authorized to see are returned.
space_avail
An unsigned 32-bit integer that specifies the size of the
attrs_sets[] array.
attr_keys[]
An array of values of type uuid_t that specify the UUIDs of
the attribute sets to be returned. The size of the attr_keys[]
array is determined by the num_attr_keys parameter.
Input/Output
cursor
A pointer to a sec_attr_cursor_t. As an input parameter,
cursor is a pointer to a sec_attr_cursor_t that is initialized
by the sec_rgy_attr_cursor_init. As an output parameter,
cursor is a pointer to a sec_attr_cursor_t that is positioned
past the attribute sets returned in this call.
Output
num_returned
A pointer to a 32-bit integer that specifies the number of
attribute sets returned in the attrs[] array.
attr_sets
An array of values of type sec_attr_t that contains the
attribute sets retrieved by UUID. The size of the array is
determined by space_avail and the length by num_returned.
num_left
A pointer to a 32-bit unsigned integer that supplies the number
of attribute sets that were found but could not be returned
because of space constraints in the attr_sets[] buffer. To
ensure that all the attributes will be returned, increase the
size of the attr_sets[] array by increasing the size of
space_avail and num_returned.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_lookup_no_expand() routine reads attribute sets. This
routine is similar to the sec_rgy_attr_lookup_by_id() routine with one
exception: for attribute sets, the sec_rgy_attr_lookup_by_id() routine
expands attribute sets and returns a sec_attr_t for each member in the
set. This call does not. Instead it returns a sec_attr_t for the set
instance only. The sec_rgy_attr_lookup_no_expand() routine is useful
for programmatic access.
cursor is a cursor of type sec_attr_cursor_t that establishes the point
in the attribute set list from which the server should start processing
the query. Use the sec_rgy_attr_cursor_init function to initialize
cursor. If cursor is uninitialized, the server begins processing the
query with the first attribute that satisfies the search criteria.
The num_left parameter contains the number of attribute sets that were
found but could not be returned because of space constraints of the
attr_sets[] array. (Note that this number may be inaccurate if the
target server allows updates between successive queries.) To obtain all
of the remaining attribute sets, set the size of the attr_sets[] array
so that it is large enough to hold the number of attributes listed in
num_left.
Permissions Required
The sec_rgy_attr_lookup_no_expand() routine requires the query
permission set for each attribute type identified in the attr_keys[]
array. These permissions are defined as part of the ACL manager set
in the schema entry of each attribute type.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL
The idl file from which dce/sec_rgy_attr.h was derived.
ERRORS
unauthorized
registry server unavailable
invalid/unsupported attribute type
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_lookup_by_id
sec_rgy_attr_lookup_by_name
4.112 – sec_rgy_attr_sch_aclmgr_strings
NAME
sec_rgy_attr_sch_aclmgr_strings - Returns printable ACL strings
associated with an ACL manager
protecting a bound to schema
object
SYNOPSIS
#include <dce/dce_attr_base.h>
void sec_rgy_attr_sch_aclmgr_strings(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
uuid_t *acl_mgr_type,
unsigned32 size_avail,
uid_t *acl_mgr_type_chain,
sec_acl_printstring_t *acl_mgr_info,
boolean32 *tokenize,
unsigned32 *total_num_printstrings,
unsigned32 *size_used,
sec_acl_printstring_t permstrings[],
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
schema_name
Reserved for future use.
acl_manager_type
A pointer to the UUID identifying the type of the ACL manager
in question. There may be more than one type of ACL manager
protecting the schema object whose ACL is bound to the input
handle. Use this parameter to distinguish them. Use
sec_rgy_attr_sch_get_acl_mgrs to acquire a list of the manager
types protecting a given schema object.
size_avail
An unsigned 32-bit integer containing the allocated length of
the permstrings[] array.
Output
acl_mgr_type_chain
If the target object ACL contains more than 32 permission bits,
chains of manager types are used: each manager type holds one
32-bit segment of permissions. The UUID returned in
acl_mgr_type_chain refers to the next ACL manager in the chain.
If there are no more ACL managers in the chain, uuid_nil is
returned.
acl_mgr_info
A pointer to a printstring that contains the ACL manager type's
name, help information, and set of supported of permission bits.
tokenize
A pointer to a variable that specifies whether or not
printstrings will be passed separately:
+ TRUE indicates that the printstrings must be printed or
passed separately.
+ FALSE indicates that the printstrings are unambiguous and
can be concatenated when printed without confusion.
total_num_printstrings
A pointer to an unsigned 32-bit integer containing the total
number of permission entries supported by this ACL manager type.
size_used
A pointer to an unsigned 32-bit integer containing the number
of permission entries returned in the permstrings[] array.
permstrings[]
An array of printstrings of type sec_acl_printstring_t.
Each entry of the array is a structure containing the
following three components:
printstring
A character string of maximum length
sec_acl_printstring_len describing the printable
representation of a specified permission.
helpstring
A character string of maximum length
sec_acl_printstring_help_len containing some text that
can be used to describe the specified permission.
permissions
A sec_acl_permset_t permission set describing the
permissions that are represented with the companion
printstring.
The array consists of one such entry for each permission supported by
the ACL manager identified by acl_mgr_type.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_aclmgr_strings() routine returns an array of
printable representations (called "printstrings") for each permission
bit or combination of permission bits the specified ACL manager
supports. The ACL manager type specified by acl_mgr_type must be one
of the types protecting the schema object bound to by h.
In addition to returning the printstrings, this routine also returns
instructions about how to print the strings in the tokenize variable.
If this variable is set to FALSE, the printstrings can be concatenated.
If it is set to TRUE, the printstrings cannot be concatenated. For
example a printstrings of r or w could be concatenated as rw without
any confusion. However, printstrings in a form of read or write,
should not be concatenated.
ACL managers often define aliases for common permission combinations.
By convention, simple entries appear at the beginning of the
printstrings[] array, and combinations appear at the end.
Permissions Required
The sec_rgy_attr_sch_scl_mgr_strings() routine requires the r permission
on the attr_schema object.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_get_acl_mgrs
4.113 – sec_rgy_attr_sch_create_entry
NAME
sec_rgy_attr_sch_create_entry - Create a schema entry
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_create_entry(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
sec_attr_schema_entry_t *schema_entry,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
schema_name
Reserved for future use.
schema_entry
A pointer to a sec_attr_schema_entry_t that contains the schema
entry values for the schema in which the entry is to be created.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_create_entry() routine creates schema entries that
define attribute types.
Permissions Required
The sec_rgy_attr_sch_create_entry() routine requires i permission
on the attr_schema object.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_bad_name
sec_attr_bad_encoding_type
sec_attr_bad_acl_mgr_set
sec_attr_bad_acl_mgr_type
sec_attr_bad_permset
sec_attr_bad_intercell_action
sec_attr_trig_bind_info_missing
sec_attr_bad_bind_info
sec_attr_bad_bind_svr_name
sec_attr_bad_bind_prot_level
sec_attr_bad_bind_authn_svc
sec_attr_bad_bind_authz_svc
sec_attr_bad_uniq_query_accept
sec_attr_bad_scope
sec_attr_bad_comment
sec_attr_type_id_exists
sec_attr_name_exists
sec_attr_unauthorized
sec_attr_svr_read_only
sec_attr_svr_unavailable
sec_attr_no_memory
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_delete_entry
sec_rgy_attr_sch_update
4.114 – sec_rgy_attr_sch_cursor_alloc
NAME
sec_rgy_attr_sch_cursor_alloc - Allocates resources to a cursor
used with the sec_rgy_attr_sch_scan
call
SYNOPSIS
void sec_rgy_att_sch_cursor_alloc(
dce_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Output
cursor
A pointer to a sec_attr_cursor_t.
status
A pointer to the completion status. On successful completion,
the call returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_cursor_alloc() call allocates resources to a
cursor used with the sec_rgy_attr_sch_scan() call. This routine,
which is a local operation, does not initialize cursor.
The sec_rgy_attr_sch_cursor_init() routine, which makes a remote
call, allocates and initializes the cursor. In addition,
sec_rgy_attr_sch_cursor_init() returns the total number of entries
found in the schema as an output parameter;
sec_rgy_attr_sch_cursor_alloc() does not.
Permissions Required
None.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.id was
derived.
ERRORS
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_cursor_init
sec_rgy_attr_sch_cursor_release
sec_rgy_attr_sch_scan
4.115 – sec_rgy_attr_sch_cursor_init
NAME
sec_rgy_attr_sch_cursor_init - Initialize and allocate a cursor used
with the sec_rgy_attr_sch_scan call
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_cursor_init(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
unsigned32 *cur_num_entries,
sec_attr_cursor_t *cursor,
error_status_t status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
schema_name
Reserved for future use.
Output
cur_num_entries
A pointer to an unsigned 32-bit integer that specifies the
total number of entries contained in the schema at the time
of this call.
cursor
A pointer to a sec_attr_cursor_t that is initialized to the
first entry in the the schema.
status
A pointer to the completion status. On successful completion,
the call returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_cursor_init() call initializes and allocates
resources to a cursor used with the sec_rgy_attr_sch_scan call. This
call makes remote calls to initialize the cursor. To limit the number
of remote calls, use the sec_rgy_attr_sch_cursor_alloc() call to
allocate cursor, but not initialize it. Be aware, however, that the
sec_rgy_attr_sch_cursor_init() call supplies the total number of entries
found in the schema as an output parameter; the
sec_rgy_attr_sch_cursor_alloc() call does not.
If the cursor iunput to sec_rgy_attr_sch_scan has not been initialized,
the sec_rgy_attr_sch_scan call will initialize it; if it has been
initialized, sec_rgy_attr_sch_scan advances it.
Permissions Required
None.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_cursor_release
sec_rgy_attr_sch_scan
sec_rgy_attr_sch_cursor_alloc
4.116 – sec_rgy_attr_sch_cursor_release
NAME
sec_rgy_attr_sch_cursor_release - Release states associated
with a cursor used by the
sec_rgy_attr_sch_scan routine
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_cursor_release(
sec_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input/Output
cursor
A pointer to a sec_attr_cursor_t. As an input parameter, cursor
must have been initialized to the first entry in a schema. As
an output parameter, cursor is uninitialized with all resources
releases.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_cursor_init() routine releases the resources
allocated to the cursor used by the sec_rgy_attr_sch_scan routine.
This call is a local operation and makes no remote calls.
Permissions Required
None.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_cursor_init
sec_rgy_attr_sch_cursor_allocate
sec_rgy_attr_sch_scan
4.117 – sec_rgy_attr_sch_cursor_reset
NAME
sec_rgy_attr_sch_cursor_reset - Resets a cursor that has been
allocated with either
sec_rgy_attr_sch_cursor_init() or
sec_rgy_attr_sch_cursor_alloc().
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void dce_attr_cursor_reset(
sec_attr_cursor_t *cursor,
error_status_t *status);
PARAMETERS
Input/Output
cursor
A pointer to a sec_attr_cursor_t. As an input parameter, an
initialized cursor. As an output parameter, cursor is reset
to the first attribute in the schema.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_cursor_reset() routine resets a dce_attr_cursor_t
that has been allocated by either a sec_rgy_attr_sch_cursor_init() or
sec_rgy_attr_sch_cursor_alloc(). The reset cursor can then be used to
process a new sec_rgy_attr_sch_scan query by reusing the cursor instead
of releasing and re-allocating it. This is a local operation and makes
no remote calls.
Permissions Required
None.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_bad_cursor
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_cursor_init
sec_rgy_attr_sch_cursor_alloc
sec_rgy_attr_sch_scan
4.118 – sec_rgy_attr_sch_delete_entry
NAME
sec_rgy_attr_sch_delete_entry - Delete a schema entry
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_delete_entry(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
uuid_t *attr_id,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
schema_name
Reserved for future use.
attr_id
A pointer to a uuid_t that identifies the schema entry to be
deleted.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_delete_entry() routine deletes a schema entry.
Because this is a radical operation that invalidates any existing
attributes of this type on objects dominated by the schema, access to
this operation should be severely limited.
Permissions Required
The sec_rgy_attr_sch_delete_entry() routine requires the d permission
on the attr_schema object.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_sch_entry_not_found
sec_attr_unauthorized
sec_attr_svr_read_only
sec_attr_svr_unavailable
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_create_entry
sec_rgy_attr_sch_update_entry
4.119 – sec_rgy_attr_sch_get_acl_mgrs
NAME
sec_rgy_attr_sch_get_acl_mgrs - Retrieve the manager types of the
ACLs protecting the objects
dominated by a named schema
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_get_acl_mgrs(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
unsigned32 size_avail,
unsigned32 *size_used,
unsigned32 *num_acl_mgr_types,
uuid_t acl_mgr_types[],
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
schema_name
Reserved for future use.
size_avail
An unsigned 32-bit integer containing the allocated length of
the acl_manager_types[] array.
Output
size_used
An unsigned 32-bit integer containing the number of output
entries returned in the acl_mgr_types[] array.
num_acl_mgr_types
An unsigned 32-bit integer containing the number of types
returned in the acl_mgr_types[] array. This may be greater
than size_used if there was not enough space allocated by
size_avail for all the manager types in the
acl_manager_types[] array.
acl_mgr_types[]
An array of the length specified in size_avail to contain UUIDs
(of type uuid_t) identifying the types of ACL managers protecting
the target object.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_get_acl_mgrs() routine returns a list of the
manager types protecting the schema object identified by context.
ACL editors and browsers can use this operation to determine the ACL
manager types protecting a selected schema object. Then, using the
sec_rgy_attr_sch_aclmgr_strings() routine, they can determine how to
format for display the permissions supported by that ACL manager type.
Permissions Required
The sec_rgy_attr_sch_get_acl_mgrs() routine requires the r permission
on the attr_schema object.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_aclmgr_strings
4.120 – sec_rgy_attr_sch_lookup_by_id
NAME
sec_rgy_attr_sch_lookup_by_id - Read a schema entry identified by UUID
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_lookup_by_id(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
uuid_t *attr_id,
sec_attr_schema_entry_t *schema_entry,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
schema_name
Reserved for future use.
attr_id
A pointer to a uuid_t that identifies a schema entry.
Output
schema_entry
A sec_attr_schema_entry_t that contains an entry identified by
attr_id.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_lookup_by_id() routine reads a schema entry
identified by attr_id. This routine is useful for programmatic access.
Permissions Required
The sec_rgy_attr_sch_lookup_by_id() routine requires the r permission
on the attr_schema object.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_sch_entry_not_found
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_lookup_by_name
sec_rgy_attr_sch_scan
4.121 – sec_rgy_attr_sch_lookup_by_name
NAME
sec_rgy_attr_sch_lookup_by_name - Read a schema entry identified by
name
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_lookup_by_name(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
char *attr_name,
sec_attr_schema_entry_t *schema_entry,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
schema_name
Reserved for future use.
attr_name
A pointer to a character string that identifies the schema entry.
Output
schema_entry
A sec_attr_schema_entry_t that contains the schema entry
identified by attr_name.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_lookup_by_name() routine reads a schema entry
identified by name. This routine is useful for use with an interactive
editor.
Permissions Required
The sec_rgy_attr_sch_lookup_by_name() routine requires the r permission
on the attr_schema object.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_sch_entry_not_found
sec_attr_bad_name
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_lookup_by_id
sec_rgy_attr_sch_scan
4.122 – sec_rgy_attr_sch_scan
NAME
sec_rgy_attr_sch_scan - Read a specified number of schema entries
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_scan(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
sec_attr_cursor_t *cursor,
unsigned32 num_to_read,
unsigned32 *num_read,
sec_attr_schema_entry_t schema_entries[],
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
schema_name
Reserved for future use.
num_to_read
An unsigned 32-bit integer specifying the size of the
schema_entries[] array and the maximum number of entries to be
returned.
Input/Output
cursor
A pointer to a sec_attr_cursor_t. As input cursor must be
allocated and can be initialized. If cursor is not initialized,
sec_rgy_attr_sch_scan will initialized. As output, cursor is
positioned at the first schema entry after the returned entries.
Output
num_read
A pointer an unsigned 32-bit integer specifying the number of
entries returned in schema_entries[].
schema_entries[]
A sec_attr_schema_entry_t that contains an array of the returned
schema entries.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_scan() routine reads schema entries. The read
begins at the entry at which the input cursor is positioned and ends
after the number of entries specified in num_to_read.
The input cursor must have been allocated by either the
sec_rgy_attr_sch_cursor_init() or the sec_rgy_attr_sch_cursor_alloc()
call. If the input cursor is not initialzed, sec_rgy_attr_sch_scan()
initializes it; if cursor is initialized, sec_rgy_attr_sch_scan()
simply advances it.
To read all entries in a schema, make successive sec_rgy_attr_sch_scan()
calls. When all entries have been read, the call returns the message
no_more_entries.
This routine is useful as a browser.
Permissions Required
The sec_rgy_attr_sch_scan() routine requires r permission on the
attr_schema object.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_bad_cursor
sec_attr_unauthorized
sec_attr_svr_unavailable
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_cursor_init
sec_rgy_attr_sch_cursor_alloc
sec_rgy_attr_sch_cursor_release
4.123 – sec_rgy_attr_sch_update_entry
NAME
sec_rgy_attr_sch_update_entry - Update a schema entry
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
void sec_rgy_attr_sch_update_entry(
sec_rgy_handle_t context,
sec_attr_component_name_t schema_name,
sec_attr_schema_entry_parts_t modify_parts,
sec_attr_schema_entry_t *schema_entry,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
schema_name
Reserved for future use.
modify_parts
A value of type sec_attr_schema_entry_parts_t that identifies the
fields in schema_entry that can be modified.
schema_entry
A pointer to a sec_attr_schema_entry_t that contains the schema
entry values for the schema entry to be updated.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_sch_update_entry() routine modifies schema entries.
Only those schema entry fields set to be modified in the
sec_attr_schema_entry_parts_t data type can be modified.
Some schema entry components can never be modified. Instead to make any
changes to these components, the schema entry must be deleted (which
deletes all attribute instances of that type) and recreated. The schema
entry components that can never be modified are listed below:
+ Attribute name
+ Reserved flag
+ Apply defaults flag
+ Intercell action flag
+ Trigger binding
+ Comment
Fields that are arrays of structures (such as acl_mgr_set and
trig_binding) are completely replaced by the new input array. This
operation cannot be used to add a new element to the existing array.
Permissions Required
The sec_rgy_attr_sch_update_entry() routine requires the M permission
on the attr_schema object.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL
The idl file from which dce/sec_rgy_attr_sch.h was derived.
ERRORS
sec_attr_field_no_update
sec_attr_bad_name
sec_attr_bad_acl_mgr_set
sec_attr_bad_acl_mgr_type
sec_attr_bad_permset
sec_attr_bad_intercell_action
sec_attr_trig_bind_info_missing
sec_attr_bad_bind_info
sec_attr_bad_bind_svr_name
sec_attr_bad_bind_prot_level
sec_attr_bad_bind_authn_svc
sec_attr_bad_bind_authz_svc
sec_attr_bad_uniq_query_accept
sec_attr_bad_comment
sec_attr_name_exists
sec_attr_sch_entry_not_found
sec_attr_unauthorized
sec_attr_svr_read_only
sec_attr_svr_unavailable
sec_attr_no_memory
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_sch_delete_entry
sec_rgy_attr_sch_create_entry
4.124 – sec_rgy_attr_test_and_update
NAME
sec_rgy_attr_test_and_update - Updates specified attribute instances
for a specified object only if a set
of control attribute instances match
the object's existing attribute instances
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_test_and_update (
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
unsigned32 num_to_test,
sec_attr_t test_attrs[],
unsigned32 num_to_write,
sec_attr_t update_attrs[],
signed32 *failure_index,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
A value of type sec_rgy_domain_t that identifies the registry
domain in which the object specified by name resides. The valid
values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
This parameter is ignored if name is policy or replist.
name A character string of type sec_rgy_name_t specifying the name
of the person, group, or organization to which the attribute
is attached.
num_to_test
An unsigned 32-bit integer that specifies the number of elements
in the test_attrs[] array. This integer must be greater than 0.
test_attrs[]
An array of values of type sec_attr_t that specifies the control
attributes. The update takes place only if the types and values
of the control attributes exactly match those of the attribute
instances on the named registry object. The size of the array is
determined by num_to_test.
num_to_write
A 32-bit integer that specifies the number of attribute
instances returned in the update_attrs[] array.
update_attrs
An array of values of type sec_attr_t that specifies the
attribute instances to be updated. The size of the array is
determined by num_to_write.
Output
failure_index
In the event of an error, failure_index is a pointer to the
element in the update_attrs[] array that caused the update to
fail. If the failure cannot be attributed to a specific
attribute, the value of failure_index is -1.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_test_and_update() routine updates an attribute only
if the set of control attributes specified in the test_attrs[] match
attributes that already exist for the object.
This update is an atomic operation: if any of the control attributes
do not match existing attributes, none of the updates are performed,
and if an update should be performed, but the write cannot occur for
whatever reason to any member of the update_attrs[] array, all updates
are aborted. The attribute causing the update to fail is identified in
failure_index. If the failure cannot be attributed to a given attribute,
failure_index contains -1.
If an attribute instance already exists which is identical in both
attr_id and attr_value to an attribute specified in in_attrs[], the
existing attribute information is overwritten by the new information.
For multi-valued attributes, every instance with the same attr_id is
overwritten with the supplied values.
If an attribute instance does not exist, it is created.
If you specify an attribute set for updating, the update applies to the
set instance, the set itself, not the members of the set. To update a
member of an attribute set, supply the UUID of the set member.
If an input attribute is associated with an update attribute trigger
server, the attribute trigger server is invoked (by the
sec_attr_trig_update() function) and the in_attr[] array is supplied
as input. The output attributes from the update attribute trigger server
are stored in the registry database and returned in the out_attrs[]
array. Note that the update attribute trigger server may modify the
values before they are used to update the registry database. This is
the only circumstance under which the values in the out_attrs[] array
differ from the values in the in_attrs[] array.
Permissions Required
The sec_rgy_attr_test_and_update() routine routine requires the test
permission and the update permission set set for each attribute type
identified in the test_attrs[] array. These permissions are defined as
part of the ACL manager set in the schema entry of each attribute type.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL
The idl file from which dce/sec_rgy_attr.h was derived.
ERRORS
control attribute has changed
unauthorized
database read only
server unavailable
invalid/unsupported attribute type
invalid encoding type
value not unique
trigger server unavailable
site read only
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_update
sec_rgy_attr_delete
4.125 – sec_rgy_attr_update
NAME
sec_rgy_attr_update - Creates and updates attribute instances for a
specified object
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_update (
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
unsigned32 num_to_write,
unsigned32 space_avail,
sec_attr_t in_attrs[],
unsigned32 *num_returned,
sec_attr_t out_attrs[],
unsigned32 *num_left,
signed32 *failure_index,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
A value of type sec_rgy_domain_t that identifies the registry
domain in which the object specified by name resides. The
valid values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
This parameter is ignored if name is policy or replist.
name A character string of type sec_rgy_name_t specifying the name
of the person, group, or organization to which the attribute
is attached.
num_to_write
A 32-bit unsigned integer that specifies the number of elements
in the in_attrs array. This integer must be greater than 0.
space_avail
A 32-bit unsigned integer that specifies the size of the
out_attrs array. This integer must be greater than 0.
in_attrs[]
An array of values of type sec_attr_t that specifies the
attribute instances to be updated. The size of the array is
determined by num_to_write.
Output
num_returned
A pointer to an unsigned 32-bit integer that specifies the
number of attribute instances returned in the out_attrs[] array.
out_attrs
An array of values of type sec_attr_t that specifies the updated
attribute instances. Not that only if these attributes were
processed by an update attribute trigger server will they differ
from the attributes in the in_attrs[] array. The size of the
array is determined by space_avail and the length by
num_returned.
num_left
A pointer to an unsigned 32-bit integer that supplies the number
of attributes that could not be returned because of space
constraints in the out_attrs[] buffer. To ensure that all the
attributes will be returned, increase the size of the
out_attrs[] array by increasing the size of space_avail and
num_returned.
failure_index
In the event of an error, failure_index is a pointer to the
element in the in_attrs[] array that caused the update to fail.
If the failure cannot be attributed to a specific attribute,
the value of failure_index is -1.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_update() routine creates new attribute instances and
updates existing attribute instances attached to a object specified by
name and Registry domain. The instances to be created or updated are
passed as an array of sec_attr_t data types. This is an atomic
operation: if the creation of any attribute in the in_attrs[] array
fails, all updates are aborted. The attribute causing the update to
fail is identified in failure_index. If the failure cannot be
attributed to a given attribute, failure_index contains -1.
The in_attrs array, which specifies the attributes to be created,
contains values of type sec_attr_t. These values are:
+ attr_id, a UUID that identifies the attribute type
+ attr_value, values of sec_attr_value_t that specify the attribute's
encoding type and values.
If an attribute instance already exists which is identical in both
attr_id and attr_value to an attribute specified in in_attrs, the
existing attribute information is overwritten by the new information.
For multi-valued attributes, every instance with the same attr_id is
overwritten with the supplied values.
If an attribute instance does not exist, it is created.
For multi-valued attributes, because every instance of the multi-valued
attribute is identified by the same UUID, every instance is overwritten
with the supplied value. To change only one of the values, you must
supply the values that should be unchanged as well as the new value.
To create instances of multi-valued attributes, create individual
sec_attr_t data types to define each multi-valued attribute instance
and then pass all of them in in the input array.
If an input attribute is associated with an update attribute trigger
server, the attribute trigger server is invoked (by the
sec_attr_trig_update() function) and the in_attr[] array is supplied
as input. The output attributes from the update attribute trigger server
are stored in the registry database and returned in the out_attrs[]
array. Note that the update attribute trigger server may modify the
values before they are used to update the registry database. This is
the only circumstance under which the values in the out_attrs[] array
differ from the values in the in_attrs[] array.
Permissions Required
The sec_rgy_attr_update() routine requires the update permission set
for each attribute type identified in the in_attrs[] array. These
permissions are defined as part of the ACL manager set in the schema
entry of each attribute type.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL
The idl file from which dce/sec_rgy_attr.h was derived.
ERRORS
unauthorized
database read only
server unavailable
invalid/unsupported attribute type
invalid encoding type
value not unique
attribute instance already exists
trigger server unavailable
site read only
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_delete
sec_rgy_attr_test_and_update
4.126 – sec_rgy_auth_plcy_get_effective
NAME
sec_rgy_auth_plcy_get_effective - Returns the effective
authentication policy for an
account
SYNOPSIS
#include <dce/policy.h>
void sec_rgy_auth_plcy_get_effective(
sec_rgy_handle_t context,
sec_rgy_login_name_t *account,
sec_rgy_plcy_auth_t *auth_policy,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
account
A pointer to the account login name (type sec_rgy_login_name_t).
A login name is composed of three character strings, containing
the principal, group, and organization (PGO) names corresponding
to the account. If all three fields contain empty strings, the
authentication policy returned is that of the registry.
Output
auth_policy
A pointer to the sec_rgy_plcy_auth_t structure to receive the
authentication policy. The authentication policy structure
contains the maximum lifetime for an authentication ticket,
and the maximum amount of time for which one can be renewed.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_auth_plcy_get_effective() routine returns the effective
authentication policy for the specified account. The authentication
policy in effect is the more restrictive of the registry and the account
policies for each policy category. If no account is specified, the
registry's authentication policy is returned.
Permissions Required
The sec_rgy_auth_plcy_get_effective() routine requires the r (read)
permission on the policy object from which the data is to be returned.
If an account is specified and an account policy exists, the routine
also requires the r (read) permission on the account principal.
FILES
SYS$COMMON:[DCE$LIBRARY]POLICY.IDL
The idl file from which dce/policy.h was derived.
ERRORS
sec_rgy_object_not_found
The specified account could not be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_auth_plcy_get_info
sec_rgy_auth_plcy_set_info
4.127 – sec_rgy_auth_plcy_get_info
NAME
sec_rgy_auth_plcy_get_info - Returns the authentication policy for
an account
SYNOPSIS
#include <dce/policy.h>
void sec_rgy_auth_plcy_get_info(
sec_rgy_handle_t context,
sec_rgy_login_name_t *account,
sec_rgy_plcy_auth_t *auth_policy,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
account
A pointer to the account login name (type sec_rgy_login_name_t).
A login name is composed of three character strings, containing
the principal, group, and organization (PGO) names corresponding
to the account.
Output
auth_policy
A pointer to the sec_rgy_plcy_auth_t structure to receive the
authentication policy. The authentication policy structure
contains the maximum lifetime for an authentication ticket,
and the maximum amount of time for which one can be renewed.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_auth_plcy_get_info() routine returns the authentication
policy for the specified account. If no account is specified, the
registry's authentication policy is returned.
Permissions Required
The sec_rgy_auth_plcy_get_info() routine requires the r (read)
permission on the policy object or account principal from which the
data is to be returned.
NOTES
The actual policy in effect will not correspond precisely to what
is returned by this call if the overriding registry authentication
policy is more restrictive than the policy for the specified account.
Use sec_rgy_auth_plcy_get_effective() to return the policy currently
in effect for the given account.
FILES
SYS$COMMON:[DCE$LIBRARY]POLICY.IDL
The idl file from which dce/policy.h was derived.
ERRORS
sec_rgy_object_not_found
No account with the given login name could be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_auth_plcy_get_effective
sec_rgy_auth_plcy_set_info
4.128 – sec_rgy_auth_plcy_set_info
NAME
sec_rgy_auth_plcy_set_info - Sets the authentication policy for an
account
SYNOPSIS
#include <dce/policy.h>
void sec_rgy_auth_plcy_set_info(
sec_rgy_handle_t context,
sec_rgy_login_name_t *account,
sec_rgy_plcy_auth_t *auth_policy,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
account
A pointer to the account login name (type sec_rgy_login_name_t).
A login name is composed of three character strings, containing
the principal, group, and organization (PGO) names corresponding
to the account. All three names must be completely specified.
auth_policy
A pointer to the sec_rgy_plcy_auth_t structure containing the
authentication policy. The authentication policy structure
contains the maximum lifetime for an authentication ticket,
and the maximum amount of time for which one can be renewed.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_auth_plcy_set_info() routine sets the indicated
authentication policy for the specified account. If no account
is specified, the authentication policy is set for the registry
as a whole.
Permissions Required
The sec_rgy_auth_plcy_set_info() routine requires the a (auth_info)
permission on the policy object or account principal for which the
data is to be set.
NOTES
The policy set on an account may be less restrictive than the policy
set for the registry as a whole. In this case, the change in policy
has no effect, since the effective policy is the most restrictive
combination of the principal and registry authentication policies.
(See the sec_rgy_auth_plcy_get_effective() routine).
FILES
SYS$COMMON:[DCE$LIBRARY]POLICY.IDL
The idl file from which dce/policy.h was derived.
ERRORS
sec_rgy_object_not_found
No account with the given login name could be found.
sec_rgy_not_authorized
The user is not authorized to update the specified record.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_auth_plcy_get_effective
sec_rgy_auth_plcy_get_info
4.129 – sec_rgy_cell_bind
NAME
sec_rgy_cell_bind - Binds to a registry in a cell
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_cell_bind(
unsigned_char_t *cell_name,
sec_rgy_bind_auth_info_t *auth_info,
sec_rgy_handle_t *context,
error_status_t *status);
PARAMETERS
Input
cell_name
A character string (type unsigned_char_t) containing the name
of the cell in question. Upon return, a Security Server for
that cell is associated with context, the registry server
handle. The cell must be specified completely and precisely.
This routine offers none of the pathname resolving services
of sec_rgy_site_bind().
auth_info
A pointer to the sec_rgy_bind_auth_info_t structure that
identifies the authentication protocol, protection level,
and authorization protocol to use in establishing the
binding. (See the rpc_binding_set_auth_info() routine).
Output
context
A pointer to a sec_rgy_handle_t variable. Upon return, this
contains a registry server handle indicating ("bound to")
the desired registry site.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_cell_bind() routine establishes a relationship with a
registry site at an arbitrary level of security. The cell_name
parameter identifies the target cell.
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_bind
4.130 – sec_rgy_cursor_reset
NAME
sec_rgy_cursor_reset - Resets the registry database cursor
SYNOPSIS
#include <dce/misc.h>
void sec_rgy_cursor_reset(
sec_rgy_cursor_t *cursor);
PARAMETERS
Input/Output
cursor A pointer into the registry database.
DESCRIPTION
The sec_rgy_cursor_reset() routine resets the database cursor to
return the first suitable entry. A cursor is a pointer into the
registry. It serves as a place holder when returning successive
items from the registry.
A cursor is bound to a particular server. In other words, a cursor
that is in use with one replica of the registry has no meaning for
any other replica. If a calling program attempts to use a cursor
from one replica with another, the cursor is reset and the routine
for which the cursor was specified returns the first item in the
database.
A cursor that is in use with one call cannot be used with another.
For example, you cannot use the same cursor on a call to
sec_rgy_acct_get_projlist() and sec_rgy_pgo_get_next(). The behavior
in this case is undefined.
FILES
SYS$COMMON:[DCE$LIBRARY]MISC.IDL
The idl file from which dce/misc.h was derived.
EXAMPLES
The following example illustrates use of the cursor within a loop.
The initial sec_rgy_cursor_reset() call resets the cursor to point
to the first item in the registry. Successive calls to
sec_rgy_pgo_get_next() return the next PGO item and update the cursor
to reflect the last item returned. When the end of the list of PGO
items is reached, the routine returns the value sec_rgy_no_more_entries
in the status parameter.
sec_rgy_cursor_reset(&cursor);
do {
sec_rgy_pgo_get_next(context, domain, scope, &cursor,
&item, name &status);
if (status == error_status_ok) {
/* Print formatted PGO item info */
}
} while (status == error_status_ok);
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_get_projlist
sec_rgy_acct_lookup
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_get_members
sec_rgy_pgo_get_next
4.131 – sec_rgy_login_get_effective
NAME
sec_rgy_login_get_effective - Returns the effective login data for
an account
SYNOPSIS
#include <dce/misc.h>
void sec_rgy_login_get_effective(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_key_t *key_parts,
sec_rgy_sid_t *sid,
sec_rgy_unix_sid_t *unix_sid,
sec_rgy_acct_user_t *user_part,
sec_rgy_acct_admin_t *admin_part,
sec_rgy_plcy_t *policy_data,
signed32 max_number,
signed32 *supplied_number,
uuid_t id_projlist[],
signed32 unix_projlist[],
signed32 *num_projects,
sec_rgy_name_t cell_name,
uuid_t *cell_uuid,
sec_override_fields_t *overridden,
error_status_t *status);
PARAMETERS
Input
context
The registry server handle.
max_number
The maximum number of projects to be returned by the call.
This must be no larger than the allocated size of the
projlist[] arrays.
Input/Output
login_name
A pointer to the account login name. A login name is composed
of the names for the account's principal, group, and
organization (PGO) items.
Output
key_parts
A pointer to the minimum abbreviation allowed when logging in
to the account. Abbreviations are not currently implemented
and the only legal value is sec_rgy_acct_key_person.
sid A pointer to a sec_rgy_sid_t structure to receive the returned
Subject Identifier (SID) for the account. This structure
consists of the UUIDs for the account's PGO items.
unix_sid
A pointer to a sec_rgy_unix_sid_t structure to receive the
returned UNIX Subject Identifier (SID) for the account.
This structure consists of the UNIX numbers for the account's
PGO items.
user_part
A pointer to a sec_rgy_acct_user_t structure to receive the
returned user data for the account.
admin_part
A pointer to a sec_rgy_acct_admin_t structure to receive the
returned administrative data for the account.
policy_data
A pointer to a sec_rgy_policy_t structure to receive the policy
data for the account. The policy data is associated with the
account's organization, as identified in the login name.
supplied_number
A pointer to the actual number of projects returned. This
will always be less than or equal to the max_number supplied
on input.
id_projlist[]
An array to receive the UUID of each project returned. The size
allocated for the array is given by max_number. If this value
is less than the total number of projects in the account project
list, multiple calls must be made to return all of the projects.
unix_projlist[]
An array to receive the UNIX number of each project returned.
The size allocated for the array is given by max_number. If
this value is less than the total number of projects in the
account project list, multiple calls must be made to return
all of the projects.
num_projects
A pointer indicating the total number of projects in the
specified account's project list.
cell_name
The name of the account's cell.
cell_uuid
The UUID for the account's cell.
overridden
A pointer to a 32-bit set of flags identifying the local
overrides, if any, for the account login information.
[NOT APPLICABLE ON OPENVMS]
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_login_get_effective() routine returns effective login
information for the specified account. Login information is
extracted from the account's entry in the registry database.
Effective login information is the login information from the
registry database.
The overridden parameter indicates which, if any, of the following local
overrides have been defined for the account:
+ The UNIX user ID
+ The group ID
+ The encrypted password
+ The account's miscellaneous information (gecos) field
+ The account's home directory
+ The account's login shell
FILES
SYS$COMMON:[DCE$LIBRARY]MISC.IDL
The idl file from which dce/misc.h was derived.
ERRORS
sec_rgy__object_not_found
The specified account could not be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_add
sec_rgy_login_get_info
4.132 – sec_rgy_login_get_info
NAME
sec_rgy_login_get_info - Returns login information for an account
SYNOPSIS
#include <dce/misc.h>
void sec_rgy_login_get_info(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_acct_key_t *key_parts,
sec_rgy_sid_t *sid,
sec_rgy_unix_sid_t *unix_sid,
sec_rgy_acct_user_t *user_part,
sec_rgy_acct_admin_t *admin_part,
sec_rgy_plcy_t *policy_data,
signed32 max_number,
signed32 *supplied_number,
uuid_t id_projlist[],
signed32 unix_projlist[],
signed32 *num_projects,
sec_rgy_name_t cell_name,
uuid_t *cell_uuid,
error_status_t *status);
PARAMETERS
Input
context
The registry server handle.
max_number
The maximum number of projects to be returned by the call. This
must be no larger than the allocated size of the projlist[]
arrays.
Input/Output
login_name
A pointer to the account login name. A login name is composed
of the names for the account's principal, group, and
organization (PGO) items.
Output
key_parts
A pointer to the minimum abbreviation allowed when logging in
to the account. Abbreviations are not currently implemented
and the only legal value is sec_rgy_acct_key_person.
sid A pointer to a sec_rgy_sid_t structure to receive the UUID's
representing the account's PGO items.
unix_sid
A pointer to a sec_rgy_unix_sid_t structure to receive the UNIX
numbers for the account's PGO items.
user_part
A pointer to a sec_rgy_acct_user_t structure to receive the
returned user data for the account.
admin_part
A pointer to a sec_rgy_acct_admin_t structure to receive the
returned administrative data for the account.
policy_data
A pointer to a sec_rgy_policy_t structure to receive the policy
data for the account. The policy data is associated with the
account's organization, as identified in the login name.
supplied_number
A pointer to the actual number of projects returned. This will
always be less than or equal to the max_number supplied on input.
id_projlist[]
An array to receive the UUID of each project returned. The size
allocated for the array is given by max_number. If this value
is less than the total number of projects in the account project
list, multiple calls must be made to return all of the projects.
unix_projlist[]
An array to receive the UNIX number of each project returned.
The size allocated for the array is given by max_number. If
this value is less than the total number of projects in the
account project list, multiple calls must be made to return
all of the projects.
num_projects
A pointer indicating the total number of projects in the
specified account's project list.
cell_name
The name of the account's cell.
cell_uuid
The UUID for the account's cell.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_login_get_info() routine returns login information for
the specified account. This information is extracted from the
account's entry in the registry database. To return any local over-
rides for the account's login data, use sec_rgy_login_get_effective().
Permissions Required
The sec_rgy_login_get_info() routine requires the r (read) permission
on the account principal from which the data is to be returned.
FILES
SYS$COMMON:[DCE$LIBRARY]MISC.IDL
The idl file from which dce/misc.h was derived.
ERRORS
sec_rgy_object_not_found
The specified account could not be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_acct_add
sec_rgy_login_get_effective
4.133 – sec_rgy_pgo_add
NAME
sec_rgy_pgo_add - Adds a PGO item to the registry database
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_add(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
sec_rgy_pgo_item_t *pgo_item,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The valid
values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
name A pointer to a sec_rgy_name_t character string containing the
name of the new PGO item.
pgo_item
A pointer to a sec_rgy_pgo_item_t structure containing the data
for the new PGO item. The data in this structure includes the
PGO item's name, UUID, UNIX number (if any), and administrative
data, such as whether the item may have (or belong to) a
concurrent group set.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_add() routine adds a PGO item to the registry database.
The PGO data consists of the following:
+ The Universal Unique Identifier (UUID) of the PGO item. Specify
NULL to have the registry server create a new UUID for an item.
+ The UNIX number for the PGO item. If the registry uses embedded
UNIX IDs (where a subset of the UUID bits represent the UNIX ID),
then the specified ID must match the UUID, if both are specified.
Use a value of -1 for the UNIX number to match any value.
+ The quota for subaccounts allowed for this item entry.
+ The full name of the PGO item.
+ Flags (in the sec_rgy_pgo_flags_t format) indicating whether
- A principal item is an alias.
- The PGO item can be deleted from the registry.
- A principal item can have a concurrent group set.
- A group item can appear in a concurrent group set.
Permissions Required
The sec_rgy_pgo_add() routine requires the i (insert) permission on the
parent directory in which the the PGO item is to be created.
NOTES
An account can be added to the registry database only when all its
constituent PGO items are already in the database, and the appropriate
membership relationships between them are established. For example, to
establish an account with principal name tom, group name writers, and
organization name hp, all three names must exist as independent PGO
items in the database. Furthermore, tom must be a member of writers,
which must be a member of hp. (See sec_rgy_acct_add() to add an
account to the registry.)
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to add the specified
PGO item.
sec_rgy_object_exists
A PGO item already exists with the name given in name.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_delete
sec_rgy_pgo_rename
sec_rgy_pgo_replace
sec_rgy_acct_add
4.134 – sec_rgy_pgo_add_member
NAME
sec_rgy_pgo_add_member - Adds a person to a group or organization
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_add_member(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t go_name,
sec_rgy_name_t person_name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the person, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_group
The go_name parameter identifies a group.
sec_rgy_domain_org
The go_name parameter identifies an organization.
go_name
A character string (type sec_rgy_name_t) containing the name
of the group or organization to which the specified person will
be added.
person_name
A character string (type sec_rgy_name_t) containing the name
of the person to be added to the membership list of the group
or organization specified by go_name.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_add_member() routine adds a member to the membership
list of a group or organization in the registry database.
Permissions Required
The sec_rgy_pgo_add_member() routine requires the M (Member_list)
permission on the group or organization item specified by go_name.
If go_name specifies a group, the routine also requires the g
(groups) permission on the principal person_name.
NOTES
An account can be added to the registry database only when all its
constituent PGO items are already in the database, and the appropriate
membership relationships between them are established. For example, to
establish an account with person name tom, group name writers, and
organization name hp, all three names must exist as independent PGO
items in the database. Furthermore, tom must be a member of writers,
which must be a member of hp. (See the sec_rgy_acct_add() routine to
add an account to the registry.)
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to add members to the
specified group or organization.
sec_rgy_bad_domain
An invalid domain was specified. A member can be added
only to a group or organization, not a person.
sec_rgy_object_not_found
The registry server could not find the specified name.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_delete_member
sec_rgy_pgo_get_members
sec_rgy_pgo_is_member
4.135 – sec_rgy_pgo_delete
NAME
sec_rgy_pgo_delete - Deletes a PGO item from the registry database
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_delete(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
name A pointer to a sec_rgy_name_t character string containing the
name of the PGO item to be deleted.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_delete() routine deletes a PGO item from the registry
database. Any account depending on the deleted PGO item is also deleted.
Permissions Required
The sec_rgy_pgo_delete() routine requires the following permissions:
+ The d (delete) permission on the parent directory that contains
the the PGO item to be deleted.
+ The D (Delete_object) permission on the PGO item itself.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to delete the
specified item.
sec_rgy_object_not_found
The registry server could not find the specified item.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
4.136 – sec_rgy_pgo_delete_member
NAME
sec_rgy_pgo_delete_member - Deletes a member of a group or
organization
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_delete_member(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t go_name,
sec_rgy_name_t person_name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the person, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_group
The go_name parameter identifies a group.
sec_rgy_domain_org
The go_name parameter identifies an organization.
go_name
A character string (type sec_rgy_name_t) containing the name
of the group or organization from which the specified person
will be deleted.
person_name
A character string (type sec_rgy_name_t) containing the name
of the person to be deleted from the membership list of the
group or organization specified by go_name.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_delete_member() routine deletes a member from the
membership list of a group or organization. Any accounts in which
the person holds the deleted group or organization membership are
also deleted.
Permissions Required
The sec_rgy_pgo_delete_member() routine requires the M (Member_list)
permission on the group or organization item specified by go_name.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to delete the
specified member.
sec_rgy_bad_domain
An invalid domain was specified. Members can exist
only for groups and organizations, not for persons.
sec_rgy_object_not_found
The specified group or organization was not found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_add_member
4.137 – sec_rgy_pgo_get_by_eff_unix_num
NAME
sec_rgy_pgo_get_by_eff_unix_num - Returns the name and data for a
PGO item identified by its
effective UNIX number
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_get_by_eff_unix_num(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t scope,
signed32 unix_id,
boolean32 allow_aliases,
sec_rgy_cursor_t *item_cursor,
sec_rgy_pgo_item_t *pgo_item,
sec_rgy_name_t name,
boolean32 *overridden,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The UNIX number identifies a principal.
sec_rgy_domain_group
The UNIX number identifies a group.
Note that this function does not support the value sec_rgy_domain_org.
scope A character string (type sec_rgy_name_t) containing the scope
of the desired search. The registry database is designed to
accommodate a tree-structured name hierarchy. The scope of a
search is the name of the branch under which the search takes
place. For example, all names in a registry might start with
/alpha, and be divided further into /beta or /gamma. To search
only the part of the database under /beta, the scope of the
search would be /alpha/beta, and any resulting PGO items would
have names beginning with this string. Note that these naming
conventions need not have anything to do with group or
organization PGO item membership lists.
unix_id
The UNIX number of the desired registry PGO item.
allow_aliases
A boolean32 value indicating whether to search for a primary
PGO item, or whether the search can be satisfied with an alias.
If TRUE, the routine returns the next entry found for the PGO
item. If FALSE, the routine returns only the primary entry.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in the
registry database. The sec_rgy_pgo_get_next() routine returns
the PGO item indicated by item_cursor, and advances the cursor
to point to the next item in the database. When the end of the
list of entries is reached, the routine returns the value
sec_rgy_no_more_entries in the status parameter. Use
sec_rgy_cursor_reset() to reset the cursor.
Output
pgo_item
A pointer to a sec_rgy_pgo_item_t structure to receive the data
for the returned PGO item. The data in this structure includes
the PGO item's name, UUID, UNIX number (if any), and
administrative data, such as whether the item, if a principal,
may have a concurrent group set. The data is as it appears in
the registry, for that UNIX number.
name A pointer to a sec_rgy_name_t character string containing the
returned name for the PGO item.
overridden
A pointer to a boolean32 value indicating whether or not the
supplied UNIX number has an entry in the local override file
(passwd_override or group_override). [NOT APPLICABLE ON OPENVMS]
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_get_by_eff_unix_num() routine returns the name and
data for a PGO item. The desired item is identified by its type
(domain) and its UNIX number.
This routine is similar to the sec_rgy_pgo_get_by_unix_num() routine.
The difference between the routines is that on UNIX,
sec_rgy_pgo_get_by_eff_unix_num() first searches the local override
files for the respective name_domain for a match with the supplied
UNIX number. If an override match is found, and an account or group
name is found in that entry, then that name is used to obtain PGO
data from the registry and the value of the overridden parameter is
set to TRUE.
The item_cursor parameter specifies the starting point for the search
through the registry database. It provides an automatic place holder
in the database. The routine automatically updates this variable to
point to the next PGO item after the returned item. The returned
cursor location can be supplied on a subsequent database access call
that also uses a PGO item cursor.
Permissions Required
The sec_rgy_pgo_get_by_eff_unix_num() routine requires the r (read)
permission on the PGO item to be viewed.
CAUTIONS
There are several different types of cursors used in the registry
Application Programmer Interface (API). Some cursors point to PGO
items, others point to members in a membership list, and others point
to account data. Do not use a cursor for one sort of object in a call
expecting another sort of object. For example, you cannot use the same
cursor on a call to sec_rgy_acct_get_projlist() and
sec_rgy_pgo_get_next(). The behavior in this case is undefined.
Furthermore, cursors are specific to a server. A cursor pointing
into one replica of the registry database is useless as a pointer
into another replica.
Use sec_rgy_cursor_reset() to renew a cursor for use with another
call or for another server.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_no_more_entries
The cursor is at the end of the list of PGO items.
sec_rgy_object_not_found
The specified PGO item was not found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_get_next
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
sec_rgy_cursor_reset
4.138 – sec_rgy_pgo_get_by_id
NAME
sec_rgy_pgo_get_by_id - Returns the name and data for a PGO item
identified by its UUID
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_get_by_id(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t scope,
uuid_t *item_id,
boolean32 allow_aliases,
sec_rgy_cursor_t *item_cursor,
sec_rgy_pgo_item_t *pgo_item,
sec_rgy_name_t name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The UUID identifies a principal.
sec_rgy_domain_group
The UUID identifies a group.
sec_rgy_domain_org
The UUID identifies an organization.
scope A character string (type sec_rgy_name_t) containing the scope
of the desired search. The registry database is designed to
accommodate a tree-structured name hierarchy. The scope of a
search is the name of the branch under which the search takes
place. For example, all names in a registry might start with
/alpha, and be divided further into /beta or /gamma. To search
only the part of the database under /beta, the scope of the
search would be /alpha/beta, and any resulting PGO items would
have names beginning with this string. Note that these naming
conventions need not have anything to do with group or
organization PGO item membership lists.
item_id
A pointer to the uuid_t variable containing the UUID (Unique
Universal Identifier) of the desired PGO item.
allow_aliases
A boolean32 value indicating whether to search for a primary
PGO item, or whether the search can be satisfied with an alias.
If TRUE, the routine returns the next entry found for the PGO
item. If FALSE, the routine returns only the primary entry.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in the
registry database. The sec_rgy_pgo_get_by_id() routine returns
the PGO item indicated by item_cursor, and advances the cursor
to point to the next item in the database. When the end of the
list of entries is reached, the routine returns
sec_rgy_no_more_entries in the status parameter. Use
sec_rgy_cursor_reset() to reset the cursor.
Output
pgo_item
A pointer to a sec_rgy_pgo_item_t structure to receive the data
for the returned PGO item. The data in this structure includes
the PGO item's name, UUID, UNIX number (if any), and
administrative data, such as whether the item, if a principal,
may have a concurrent group set.
name A pointer to a sec_rgy_name_t character string containing the
returned name for the PGO item.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_get_by_id() routine returns the name and data for
a PGO item. The desired item is identified by its type (domain) and
its UUID.
The item_cursor parameter specifies the starting point for the search
through the registry database. It provides an automatic place holder
in the database. The routine automatically updates this variable to
point to the next PGO item after the returned item. The returned
cursor location can be supplied on a subsequent database access call
that also uses a PGO item cursor.
Permissions Required
The sec_rgy_pgo_get_by_id() routine requires the r (read) permission
on the PGO item to be viewed.
CAUTIONS
There are several different types of cursors used in the registry
Application Programmer Interface (API). Some cursors point to PGO
items, others point to members in a membership list, and others point
to account data. Do not use a cursor for one sort of object in a call
expecting another sort of object. For example, you cannot use the
same cursor on a call to sec_rgy_acct_get_projlist() and
sec_rgy_pgo_get_next(). The behavior in this case is undefined.
Furthermore, cursors are specific to a server. A cursor pointing
into one replica of the registry database is useless as a pointer
into another replica.
Use sec_rgy_cursor_reset() to renew a cursor for use with another
call or for another server.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_no_more_entries
The cursor is at the end of the list of PGO items.
sec_rgy_object_not_found
The specified PGO item was not found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_get_next
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
sec_rgy_cursor_reset
4.139 – sec_rgy_pgo_get_by_name
NAME
sec_rgy_pgo_get_by_name - Returns the data for a named PGO item
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_get_by_name(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t pgo_name,
sec_rgy_cursor_t *item_cursor,
sec_rgy_pgo_item_t *pgo_item,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
pgo_name
A character string (type sec_rgy_name_t) containing the name
of the principal, group, or organization to search for.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in the
registry database. The sec_rgy_pgo_get_by_name() routine
returns the PGO item indicated by item_cursor, and advances
the cursor to point to the next item in the database. When the
end of the list of entries is reached, the routine returns the
value sec_rgy_no_more_entries in the status parameter. Use
sec_rgy_cursor_reset() to reset the cursor.
Output
pgo_item
A pointer to a sec_rgy_pgo_item_t structure to receive the data
for the returned PGO item. The data in this structure includes
the PGO item's name, UUID, UNIX number (if any), and
administrative data, such as whether the item, if a principal,
may have a concurrent group set.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_get_by_name() routine returns the data for a named PGO
item from the registry database. The desired item is identified by
its type (name_domain) and name.
The item_cursor parameter specifies the starting point for the search
through the registry database. It provides an automatic place holder
in the database. The routine automatically updates this variable to
point to the next PGO item after the returned item. The returned
cursor location can be supplied on a subsequent database access call
that also uses a PGO item cursor.
Permissions Required
The sec_rgy_pgo_get_by_name() routine requires the r (read) permission
on the PGO item to be viewed.
CAUTIONS
There are several different types of cursors used in the registry
Application Programmer Interface (API). Some cursors point to PGO
items, others point to members in a membership list, and others point
to account data. Do not use a cursor for one sort of object in a call
expecting another sort of object. For example, you cannot use the
same cursor on a call to sec_rgy_acct_get_projlist() and
sec_rgy_pgo_get_next(). The behavior in this case is undefined.
Furthermore, cursors are specific to a server. A cursor pointing into
one replica of the registry database is useless as a pointer into
another replica.
Use sec_rgy_cursor_reset() to renew a cursor for use with another
call or for another server.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_no_more_entries
The cursor is at the end of the list of PGO items.
sec_rgy_object_not_found
The specified PGO item was not found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_get_next
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
sec_rgy_cursor_reset
4.140 – sec_rgy_pgo_get_by_unix_num
NAME
sec_rgy_pgo_get_by_unix_num - Returns the name and data for a PGO
item identified by its UNIX ID
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_get_by_unix_num(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t scope,
signed32 unix_id,
boolean32 allow_aliases,
sec_rgy_cursor_t *item_cursor,
sec_rgy_pgo_item_t *pgo_item,
sec_rgy_name_t name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The UNIX number identifies a principal.
sec_rgy_domain_group
The UNIX number identifies a group.
sec_rgy_domain_org
The UNIX number identifies an organization.
scope A character string (type sec_rgy_name_t) containing the scope
of the desired search. The registry database is designed to
accommodate a tree-structured name hierarchy. The scope of a
search is the name of the branch under which the search takes
place. For example, all names in a registry might start with
/alpha, and be divided further into /beta or /gamma. To search
only the part of the database under /beta, the scope of the
search would be /alpha/beta, and any resulting PGO items would
have names beginning with this string. Note that these naming
conventions need not have anything to do with group or
organization PGO item membership lists.
unix_id
The UNIX number of the desired registry PGO item.
allow_aliases
A boolean32 value indicating whether to search for a primary
PGO item, or whether the search can be satisfied with an alias.
If TRUE, the routine returns the next entry found for the PGO
item. If FALSE, the routine returns only the primary entry.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in the
registry database. The sec_rgy_pgo_get_by_unix_num() routine
returns the PGO item indicated by item_cursor, and advances
the cursor to point to the next item in the database. When
the end of the list of entries is reached, the routine returns
the value sec_rgy_no_more_entries in the status parameter.
Use sec_rgy_cursor_reset() to reset the cursor.
Output
pgo_item
A pointer to a sec_rgy_pgo_item_t structure to receive the data
for the returned PGO item. The data in this structure includes
the PGO item's name, UUID, UNIX number (if any), and
administrative data, such as whether the item, if a principal,
may have a concurrent group set.
name A pointer to a sec_rgy_name_t character string containing the
returned name for the PGO item.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_get_by_unix_num() routine returns the name and data
for a PGO item. The desired item is identified by its type (domain)
and its UNIX number.
The item_cursor parameter specifies the starting point for the search
through the registry database. It provides an automatic place holder
in the database. The routine automatically updates this variable to
point to the next PGO item after the returned item. The returned
cursor location can be supplied on a subsequent database access call
that also uses a PGO item cursor.
Permissions Required
The sec_rgy_pgo_get_by_unix_num() routine requires the r (read)
permission on the PGO item to be viewed.
CAUTIONS
There are several different types of cursors used in the registry
Application Programmer Interface (API). Some cursors point to PGO
items, others point to members in a membership list, and others point
to account data. Do not use a cursor for one sort of object in a call
expecting another sort of object. For example, you cannot use the
same cursor on a call to sec_rgy_acct_get_projlist() and
sec_rgy_pgo_get_next(). The behavior in this case is undefined.
Furthermore, cursors are specific to a server. A cursor pointing
into one replica of the registry database is useless as a pointer
into another replica.
Use sec_rgy_cursor_reset() to renew a cursor for use with another
call or for another server.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_no_more_entries
The cursor is at the end of the list of PGO items.
sec_rgy_object_not_found
The specified PGO item was not found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_next
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
sec_rgy_cursor_reset
4.141 – sec_rgy_pgo_get_members
NAME
sec_rgy_pgo_get_members - Returns the membership list for a specified
group or organization or returns the set of
groups in which the specified principal is
a member.
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_get_members(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t go_name,
sec_rgy_cursor_t *member_cursor,
signed32 max_members,
sec_rgy_member_t member_list[],
signed32 *number_supplied,
signed32 *number_members,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a secd server. Use sec_rgy_site_open()
to acquire a bound handle.
name_domain
This variable specifies whether go_name identifies a principal,
group, or organization. The valid values are as follows:
sec_rgy_domain_group
The go_name parameter identifies a group.
sec_rgy_domain_org
The go_name parameter identifies an organization.
sec_rgy_domain_person
The go_name parameter identifies an principal.
go_name
A character string (type sec_rgy_name_t) that contains the name
of a group, organization, or principal. If go_name is the name
of a group or organization, the call returns the group's or
organization's member list. If go_name is the name of a
principal, the call returns a list of all groups in which the
principal is a member. (Contrast this with the
sec_rgy_acct_get_proj call, which returns only those groups in
which the principal is a member and that have been marked to be
included in the principal's project list.)
max_members
A signed32 variable containing the allocated dimension of the
member_list[] array. This is the maximum number of members or
groups that can be returned by a single call.
Input/Output
member_cursor
An opaque pointer to a specific entry in the membership list
or list of groups. The returned list begins with the entry
specified by member_cursor. Upon return, the cursor points to
the next entry after the last one returned. If there are no
more entries, the routine returns the value
sec_rgy_no_more_entries in the status parameter. Use
sec_rgy_cursor_reset() to reset the cursor to the beginning
of the list.
Output
member_list[]
An array of character strings to receive the returned member
or group names. The size allocated for the array is given by
max_number. If this value is less than the total number of
members or group names, multiple calls must be made to return
all of the members or groups.
number_supplied
A pointer to a signed32 variable to receive the number of
members or groups actually returned in member_list[].
number_members
A pointer to a signed32 variable to receive the total number
of members or groups. If this number is greater than
number_supplied, multiple calls to sec_rgy_pgo_get_members()
are necessary. Use the member_cursor parameter to coordinate
successive calls.
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_get_members() routine returns a list of the members in
the specified group or organization, or a list of groups in which a
specified principal is a member.
The member_cursor parameter specifies the starting point for the search
through the registry database. It provides an automatic place holder
in the database. The routine automatically updates member_cursor to
point to the next member or group (if any) after the returned list. If
not all of the members or groups are returned, the updated cursor can
be supplied on successive calls to return the remainder of the list.
Permissions Required
The sec_rgy_pgo_get_members() routine requires the r (read) permission
on the group, organization, or principal object specified by go_name.
CAUTIONS
There are several different types of cursors used in the registry
Application Programmer Interface (API). Some cursors point to PGO
items, others point to members in a membership list, and others point
to account data. Do not use a cursor for one sort of object in a call
expecting another sort of object. For example, you cannot use the same
cursor on a call to sec_rgy_acct_get_projlist() and
sec_rgy_pgo_get_next(). The behavior in this case is undefined.
Furthermore, cursors are specific to a server. A cursor pointing into
one replica of the registry database is useless as a pointer into
another replica.
Use sec_rgy_cursor_reset() to renew a cursor for use with another call
or for another server.
RETURN VALUES
The routine returns:
+ The names of the groups or members in member_list[]
+ The number of members or groups returned by the call in
number_supplied
+ The total number of members in the group or organization, or the
total number of groups in which the principal is a member in
number_members
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_no_more_entries
The cursor points to the end of the membership list for
a group or organization or to the end of the list of
groups for a principal.
sec_rgy_object_not_found
The specified group, organization, or principal could
not be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add_member
sec_rgy_cursor_reset
sec_rgy_pgo_is_member
sec_rgy_acct_get_proj
4.142 – sec_rgy_pgo_get_next
NAME
sec_rgy_pgo_get_next - Returns the next PGO item in the registry
database
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_get_next(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t scope,
sec_rgy_cursor_t *item_cursor,
sec_rgy_pgo_item_t *pgo_item,
sec_rgy_name_t name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group,
or organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
Returns the next principal item.
sec_rgy_domain_group
Returns the next group item.
sec_rgy_domain_org
Returns the next organization item.
scope A character string (type sec_rgy_name_t) containing the scope
of the desired search. The registry database is designed to
accommodate a tree-structured name hierarchy. The scope of a
search is the name of the branch under which the search takes
place. For example, all names in a registry might start with
/alpha, and be divided further into /beta or /gamma. To search
only the part of the database under /beta, the scope of the
search would be /alpha/beta, and any resulting PGO items would
have names beginning with this string. Note that these naming
conventions need not have anything to do with group or
organization PGO item membership lists.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in the
registry database. The sec_rgy_pgo_get_next() routine returns
the PGO item indicated by item_cursor, and advances the cursor
to point to the next item in the database. When the end of the
list of entries is reached, the routine returns the value
sec_rgy_no_more_entries in the status parameter. Use
sec_rgy_cursor_reset() to reset the cursor.
Output
pgo_item
A pointer to a sec_rgy_pgo_item_t structure to receive the data
for the returned PGO item. The data in this structure includes
the PGO item's name, UUID, UNIX number (if any), and
administrative data, such as whether the item, if a principal,
may have a concurrent group set.
name A pointer to a sec_rgy_name_t character string containing the
name of the returned PGO item.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_get_next() routine returns the data and name for the
PGO in the registry database indicated by item_cursor. It also
advances the cursor to point to the next PGO item in the database.
Successive calls to this routine return all the PGO items in the
database of the specified type (given by name_domain), in storage order.
The PGO data consists of the following:
+ The Universal Unique Identifier (UUID) of the PGO item.
+ The UNIX number for the PGO item.
+ The quota for subaccounts.
+ The full name of the PGO item.
+ Flags indicating whether
- A principal item is an alias.
- The PGO item can be deleted.
- A principal item can have a concurrent group set.
- A group item can appear on a concurrent group set.
Permissions Required
The sec_rgy_pgo_get_next() routine requires the r (read) permission
on the PGO item to be viewed.
CAUTIONS
There are several different types of cursors used in the registry
Application Programmer Interface (API). Some cursors point to PGO
items, others point to members in a membership list, and others
point to account data. Do not use a cursor for one sort of object
in a call expecting another sort of object. For example, you cannot
use the same cursor on a call to sec_rgy_acct_get_projlist() and
sec_rgy_pgo_get_next(). The behavior in this case is undefined.
Furthermore, cursors are specific to a server. A cursor pointing
into one replica of the registry database is useless as a pointer
into another replica.
Use sec_rgy_cursor_reset() to renew a cursor for use with another
call or for another server.
RETURN VALUES
The routine returns the data for the returned PGO item in pgo_item
and the name in name.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_no_more_entries
The cursor is at the end of the list of PGO items.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_cursor_reset
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_unix_num_to_id
4.143 – sec_rgy_pgo_id_to_name
NAME
sec_rgy_pgo_id_to_name - Returns the name for a PGO item identified
by its UUID
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_id_to_name(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
uuid_t *item_id,
sec_rgy_name_t pgo_name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The item_id parameter identifies a principal.
sec_rgy_domain_group
The item_id parameter identifies a group.
sec_rgy_domain_org
The item_id parameter identifies an organization.
item_id
A pointer to the uuid_t variable containing the input UUID
(Unique Universal Identifier).
Output
pgo_name
A character string (type sec_rgy_name_t) containing the name
of the principal, group, or organization with the input UUID.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_id_to_name() routine returns the name of the PGO item
having the specified UUID.
Permissions Required
The sec_rgy_pgo_id_to_name() routine requires at least one permission
of any kind on the PGO item to be viewed.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_object_not_found
No item with the specified UUID could be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
4.144 – sec_rgy_pgo_id_to_unix_num
NAME
sec_rgy_pgo_id_to_unix_num - Returns the UNIX number for a PGO
item identified by its UUID
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_id_to_unix_num(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
uuid_t *item_id,
signed32 *item_unix_id,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The item_id parameter identifies a principal.
sec_rgy_domain_group
The item_id parameter identifies a group.
sec_rgy_domain_org
The item_id parameter identifies an organization.
item_id
A pointer to the uuid_t variable containing the input UUID
(Unique Universal Identifier).
Output
item_unix_id
A pointer to the signed32 variable to receive the returned UNIX
number for the PGO item.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_id_to_unix_num() routine returns the UNIX number
for the PGO item having the specified UUID.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_object_not_found
No item with the specified UUID could be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_name
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
4.145 – sec_rgy_pgo_is_member
NAME
sec_rgy_pgo_is_member - Checks group or organization membership
SYNOPSIS
#include <dce/pgo.h>
boolean32 sec_rgy_pgo_is_member(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t go_name,
sec_rgy_name_t person_name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_group
The go_name parameter identifies a group.
sec_rgy_domain_org
The go_name parameter identifies an organization.
go_name
A character string (type sec_rgy_name_t) containing the name
of the group or organization whose membership list is in
question.
person_name
A character string (type sec_rgy_name_t) containing the name
of the principal whose membership in the group or organization
specified by go_name is in question.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_is_member() routine tests whether the specified
principal is a member of the named group or organization.
Permissions Required
The sec_rgy_pgo_is_member() routine requires the t (test) permission
on the group or organization item specified by go_name.
RETURN VALUES
The routine returns TRUE if the principal is a member of the named
group or organization. If the principal is not a member, the routine
returns FALSE.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_object_not_found
The named group or organization was not found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add_member
sec_rgy_pgo_get_members
4.146 – sec_rgy_pgo_name_to_id
NAME
sec_rgy_pgo_name_to_id - Returns the UUID for a named PGO item
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_name_to_id(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t pgo_name,
uuid_t *item_id,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
pgo_name
A character string (type sec_rgy_name_t) containing the name
of the principal, group, or organization whose UUID is desired.
Output
item_id
A pointer to the uuid_t variable containing the UUID (Unique
Universal Identifier) of the resulting PGO item.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_name_to_id() routine returns the UUID associated
with the named PGO item.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_object_not_found
The specified PGO item could not be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_unix_num_to_id
4.147 – sec_rgy_pgo_name_to_unix_num
NAME
sec_rgy_pgo_name_to_unix_num - Returns the UNIX number for a PGO item
identified by its name
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_name_to_unix_num(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t pgo_name,
signed32 *item_unix_id,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
pgo_name
A character string containing the name of the PGO item in
question.
Output
item_unix_id
A pointer to the signed32 variable to receive the returned UNIX
number for the PGO item.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_name_to_unix_num() routine returns the UNIX number
for the PGO item having the specified name.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_object_not_found
No item with the specified UUID could be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_name
sec_rgy_pgo_name_to_id
sec_rgy_pgo_unix_num_to_id
4.148 – sec_rgy_pgo_rename
NAME
sec_rgy_pgo_rename - Changes the name of a PGO item in the registry
database
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_rename(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t old_name,
sec_rgy_name_t new_name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
old_name
A pointer to a sec_rgy_name_t character string containing the
existing name of the PGO item.
new_name
A pointer to a sec_rgy_name_t character string containing the new
name for the PGO item.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_rename() routine renames a PGO item in the registry
database.
Permissions Required
If the sec_rgy_pgo_rename() routine is performing a rename within a
directory, it requires the n (name) permission on the old name of the
PGO item. If the routine is performing a move between directories, it
requires the following permissions:
+ The d (delete) permission on the parent directory that contains the
PGO item.
+ The n (name) permission on the old name of the PGO item.
+ The i (insert) permission on the parent directory in which the PGO
item is to be added under the new name.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to change the name
of the specified PGO item.
sec_rgy_object_not_found
The registry server could not find the specified PGO item.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_replace
4.149 – sec_rgy_pgo_replace
NAME
sec_rgy_pgo_replace - Replaces the data in an existing PGO item
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_replace(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t pgo_name,
sec_rgy_pgo_item_t *pgo_item,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
pgo_name
A character string (type sec_rgy_name_t) containing the name
of the principal, group, or organization whose data is to be
replaced.
pgo_item
A pointer to a sec_rgy_pgo_item_t structure containing the new
data for the PGO item. The data in this structure includes the
PGO item's name, UUID, UNIX number (if any), and administrative
data, such as whether the item, if a principal, may have a
concurrent group set.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_replace() routine replaces the data associated with
a PGO item in the registry database.
The UNIX ID and UUID of a PGO item cannot be replaced. To change the
UNIX ID or UUID, the existing PGO item must be deleted and a new PGO
item added in its place. The one exception to this rule is that the
UNIX ID can be replaced in the PGO item for a cell principal. The
reason for this exception is that the UUID for a cell principal does
not contain an embedded UNIX ID.
Permissions Required
The sec_rgy_pgo_replace() routine requires at least one of the
following permissions:
+ The m (mgmt_info) permission on the PGO item, if quota or flags
is being set.
+ The f (fullname) permission on the PGO item, if fullname is being
set.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_not_authorized
The client program is not authorized to replace the
specified PGO item.
sec_rgy_object_not_found
No PGO item was found with the given name.
sec_rgy_unix_id_changed
The UNIX number of the PGO item was changed.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_delete
sec_rgy_pgo_rename
4.150 – sec_rgy_pgo_unix_num_to_id
NAME
sec_rgy_pgo_unix_num_to_id - Returns the UUID for a PGO item
identified by its UNIX number
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_unix_num_to_id(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
signed32 item_unix_id,
uuid_t *item_id,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
This variable identifies the type of the principal, group, or
organization (PGO) item identified by the given name. The
valid values are as follows:
sec_rgy_domain_person
The item_unix_id parameter identifies a principal.
sec_rgy_domain_group
The item_unix_id parameter identifies a group.
sec_rgy_domain_org
The item_unix_id parameter identifies an
organization.
item_unix_id
The signed32 variable containing the UNIX number for the PGO
item.
Output
item_id
A pointer to the uuid_t variable containing the UUID (Unique
Universal Identifier) of the resulting PGO item.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_unix_num_to_id() routine returns the Universal Unique
Identifier (UUID) for a PGO item that has the specified UNIX number.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_object_not_found
No item with the specified UNIX number could be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
4.151 – sec_rgy_pgo_unix_num_to_name
NAME
sec_rgy_pgo_unix_num_to_name - Returns the name for a PGO item
identified by its UNIX number
SYNOPSIS
#include <dce/pgo.h>
void sec_rgy_pgo_unix_num_to_name(
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
signed32 item_unix_id,
sec_rgy_name_t pgo_name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
The type of the principal, group, or organization (PGO) item
identified by item_unix_id. Valid values are as follows:
sec_rgy_domain_person
The item_unix_id parameter identifies a principal.
sec_rgy_domain_group
The item_unix_id parameter identifies a group.
sec_rgy_domain_org
The item_unix_id parameter identifies an
organization.
item_unix_id
The signed32 variable containing the UNIX number for the PGO
item.
Output
pgo_name
A character string containing the name of the PGO item in
question.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_pgo_unix_num_to_name() routine returns the name for a PGO
item that has the specified UNIX number.
Permissions Required
The sec_rgy_pgo_unix_num_to_name() routine requires at least one
permission of any kind on the PGO item identified by item_unix_id.
FILES
SYS$COMMON:[DCE$LIBRARY]PGO.IDL
The idl file from which dce/pgo.h was derived.
ERRORS
sec_rgy_object_not_found
No item with the specified UNIX number could be found.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_pgo_add
sec_rgy_pgo_get_by_id
sec_rgy_pgo_get_by_name
sec_rgy_pgo_get_by_unix_num
sec_rgy_pgo_id_to_name
sec_rgy_pgo_id_to_unix_num
sec_rgy_pgo_name_to_id
4.152 – sec_rgy_plcy_get_effective
NAME
sec_rgy_plcy_get_effective - Returns the effective policy for an
organization
SYNOPSIS
#include <dce/policy.h>
void sec_rgy_plcy_get_effective(
sec_rgy_handle_t context,
sec_rgy_name_t organization,
sec_rgy_plcy_t *policy_data,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
organization
A character string (type sec_rgy_name_t) containing the name
of the organization for which the policy data is to be returned.
If this string is empty, the routine returns the registry's
policy data.
Output
policy_data
A pointer to the sec_rgy_plcy_t structure to receive the
authentication policy. This structure contains the minimum
length of a user's password, the lifetime of a password, the
expiration date of a password, the lifetime of the entire
account, and some flags describing limitations on the password
spelling.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_plcy_get_effective() routine returns the effective policy
for the specified organization.
The effective policy data is the most restrictive combination of the
registry and the organization policies.
The policy data consists of the following:
+ The password expiration date. This is the date on which account
passwords will expire.
+ The minimum length allowed for account passwords.
+ The period of time (life span) for which account passwords will be
valid.
+ The period of time (life span) for which accounts will be valid.
+ Flags indicating whether account passwords can consist entirely
of spaces or entirely of alphanumeric characters.
Permissions Required
The sec_rgy_plcy_get_effective() routine requires the r (read)
permission on the policy object from which the data is to be returned.
If an organization is specified, the routine also requires the r
(read) permission on the organization.
NOTES
If no organization is specified, the routine returns the registry's
policy data. To return the effective policy, an organization must be
specified. This is because the routine compares the registry's
policy data with that of the organization to determine which is more
restrictive.
FILES
SYS$COMMON:[DCE$LIBRARY]POLICY.IDL
The idl file from which dce/policy.h was derived.
ERRORS
sec_rgy_object_not_found
The registry server could not find the specified
organization.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_plcy_get_info
sec_rgy_plcy_set_info
4.153 – sec_rgy_plcy_get_info
NAME
sec_rgy_plcy_get_info - Returns the policy for an organization
SYNOPSIS
#include <dce/policy.h>
void sec_rgy_plcy_get_info(
sec_rgy_handle_t context,
sec_rgy_name_t organization,
sec_rgy_plcy_t *policy_data,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
organization
A character string (type sec_rgy_name_t) containing the name
of the organization for which the policy data is to be returned.
If this string is empty, the routine returns the registry's
policy data.
Output
policy_data
A pointer to the sec_rgy_plcy_t structure to receive the
authentication policy. This structure contains the minimum
length of a user's password, the lifetime of a password, the
expiration date of a password, the lifetime of the entire
account, and some flags describing limitations on the password
spelling.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_plcy_get_info() routine returns the policy data for the
specified organization. If no organization is specified, the
registry's policy data is returned.
The policy data consists of the following:
+ The password expiration date. This is the date on which account
passwords will expire.
+ The minimum length allowed for account passwords.
+ The period of time (life span) for which account passwords will be
valid.
+ The period of time (life span) for which accounts will be valid.
+ Flags indicating whether account passwords can consist entirely
of spaces or entirely of alphanumeric characters.
Permissions Required
The sec_rgy_plcy_get_info() routine requires the r (read) permission
on the policy object or organization from which the data is to be
returned.
NOTES
The returned policy may not be in effect if the overriding
registry authorization policy is more restrictive. (See the
sec_rgy_auth_plcy_get_effective() routine.)
FILES
SYS$COMMON:[DCE$LIBRARY]POLICY.IDL
The idl file from which dce/policy.h was derived.
ERRORS
sec_rgy_object_not_found
The registry server could not find the specified
organization.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_plcy_get_effective_info
sec_rgy_plcy_set_info
4.154 – sec_rgy_plcy_set_info
NAME
sec_rgy_plcy_set_info - Sets the policy for an organization
SYNOPSIS
#include <dce/policy.h>
void sec_rgy_plcy_set_info(
sec_rgy_handle_t context,
sec_rgy_name_t organization,
sec_rgy_plcy_t *policy_data,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
organization
A character string (type sec_rgy_name_t) containing the name
of the organization for which the policy data is to be returned.
If this string is empty, the routine sets the registry's policy
data.
policy_data
A pointer to the sec_rgy_plcy_t structure containing the
authentication policy. This structure contains the minimum
length of a user's password, the lifetime of a password, the
expiration date of a password, the lifetime of the entire
account, and some flags describing limitations on the password
spelling.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_plcy_set_info() routine sets the authentication policy
for a specified organization. If no organization is specified, the
registry's policy data is set.
Policy data can be returned or set for individual organizations and
for the registry as a whole.
Permissions Required
The sec_rgy_plcy_set_info() routine requires the m (mgmt_info)
permission on the policy object or organization for which the data
is to be set.
NOTES
The policy set on an account may be less restrictive than the policy
set for the registry as a whole. In this case, the changes in policy
have no effect, since the effective policy is the most restrictive
combination of the organization and registry authentication policies.
(See the sec_rgy_auth_plcy_get_effective() routine.)
FILES
SYS$COMMON:[DCE$LIBRARY]POLICY.IDL
The idl file from which dce/policy.h was derived.
ERRORS
sec_rgy_not_authorized
The user is not authorized to perform this operation.
sec_rgy_object_not_found
The registry server could not find the specified
organization.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_plcy_get_effective
sec_rgy_plcy_get_info
4.155 – sec_rgy_properties_get_info
NAME
sec_rgy_properties_get_info - Returns registry properties
SYNOPSIS
#include <dce/policy.h>
void sec_rgy_properties_get_info(
sec_rgy_handle_t context,
sec_rgy_properties_t *properties,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
Output
properties
A pointer to a sec_rgy_properties_t structure to receive the
returned property information. A registry's property information
contains information such as the default and minimum lifetime
and other restrictions on privilege attribute certificates, the
realm authentication name, and whether or not this replica of
the registry supports updates.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_properties_get_info() routine returns a list of the registry
properties.
The property information consists of the following:
read_version
A stamp specifying the earliest version of the registry server
software that can read from this registry.
write_version
A stamp specifying the earliest version of the registry server
software that can write to this registry.
minimum_ticket_lifetime
The minimum period of time for which an authentication ticket
remains valid.
default_certificate_lifetime
The default period of time for which an authentication
certificate (ticket-granting ticket) remains valid. A process
can request an authentication certificate with a longer
lifetime. Note that the maximum lifetime for an authentication
certificate cannot exceed the lifetime established by the
effective policy for the requesting account.
low_unix_id_person
The lowest UNIX ID that can be assigned to a principal in the
registry.
low_unix_id_group
The lowest UNIX ID that can be assigned to a group in the
registry.
low_unix_id_org
The lowest UNIX ID that can be assigned to an organization in
the registry.
max_unix_id
The maximum UNIX ID that can be used for any item in the
registry.
realm A character string naming the cell controlled by this registry.
realm_uuid
The UUID of the cell controlled by this registry.
flags Flags indicating whether
sec_rgy_prop_readonly
If TRUE, the registry database is read-only.
sec_rgy_prop_auth_cert_unbound
If TRUE, privilege attribute certificates can be
generated for use at any site.
sec_rgy_prop_shadow_password
If FALSE, passwords can be distributed over the
network. If this flag is TRUE, passwords will be
stripped from the returned data to the
sec_rgy_acct_lookup(), and other calls that return
an account's encoded password.
sec_rgy_prop_embedded_unix_id
All registry UUIDs contain embedded UNIX IDs. This
implies that the UNIX ID of any registry object
cannot be changed, since UUIDs are immutable.
Permissions Required
The sec_rgy_properties_get_info() routine requires the r (read)
permission on the policy object from which the property information
is to be returned.
FILES
SYS$COMMON:[DCE$LIBRARY]POLICY.IDL
The idl file from which dce/policy.h was derived.
ERRORS
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_properties_set_info
4.156 – sec_rgy_properties_set_info
NAME
sec_rgy_properties_set_info - Sets registry properties
SYNOPSIS
#include <dce/policy.h>
void sec_rgy_properties_set_info(
sec_rgy_handle_t context,
sec_rgy_properties_t *properties,
error_status_t *status);
PARAMETERS
Input
context
The registry server handle. An opaque handle bound to a
registry server. Use sec_rgy_site_open() to acquire a bound
handle.
properties
A pointer to a sec_rgy_properties_t structure containing the
registry property information to be set. A registry's property
information contains information such as the default and
minimum lifetime and other restrictions on privilege attribute
certificates, the realm authentication name, and whether or not
this replica of the registry supports updates.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_properties_set_info() routine sets the registry properties.
The property information consists of the following:
read_version
A stamp specifying the earliest version of the registry server
software that can read from this registry.
write_version
A stamp specifying the earliest version of the registry server
software that can write to this registry.
minimum_ticket_lifetime
The minimum period of time for which an authentication ticket
remains valid.
default_certificate_lifetime
The default period of time for which an authentication
certificate (ticket-granting ticket) remains valid. A process
can request an authentication certificate with a longer
lifetime. Note that the maximum lifetime for an authentication
certificate cannot exceed the lifetime established by the
effective policy for the requesting account.
low_unix_id_person
The lowest UNIX ID that can be assigned to a principal in the
registry.
low_unix_id_group
The lowest UNIX ID that can be assigned to a group in the
registry.
low_unix_id_org
The lowest UNIX ID that can be assigned to an organization in
the registry.
max_unix_id
The maximum UNIX ID that can be used for any item in the
registry.
realm A character string naming the cell controlled by this registry.
realm_uuid
The UUID of the cell controlled by this registry.
flags Flags indicating whether
sec_rgy_prop_readonly
If TRUE, the registry database is read-only.
sec_rgy_prop_auth_cert_unbound
If TRUE, privilege attribute certificates can be
generated for use at any site.
sec_rgy_prop_shadow_password
If FALSE, passwords can be distributed over the
network. If this flag is TRUE, passwords will be
stripped from the returned data to the
sec_rgy_acct_lookup(), and other calls that return
an account's encoded password.
sec_rgy_prop_embedded_unix_id
All registry UUIDs contain embedded UNIX IDs. This
implies that the UNIX ID of any registry object
cannot be changed, since UUIDs are immutable.
Permissions Required
The sec_rgy_properties_set_info() routine requires the m (mgmt_info)
permission on the policy object for which the property information is
to be set.
FILES
SYS$COMMON:[DCE$LIBRARY]POLICY.IDL
The idl file from which dce/policy.h was derived.
ERRORS
sec_rgy_not_authorized
The user is not authorized to change the registry
properties.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_properties_get_info
4.157 – sec_rgy_site_bind
NAME
sec_rgy_site_bind - Binds to a registry site
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_bind(
unsigned_char_t *site_name,
sec_rgy_bind_auth_info_t *auth_info,
sec_rgy_handle_t *context,
error_status_t *status);
PARAMETERS
Input
site_name
A character string (type unsigned_char_t) containing the name
of the registry site to bind to. Supply this name in any of
the following forms:
+ To randomly choose a site to bind to in the named cell,
specify a cell name (for example, /.../r_d.com or /.:
for the local cell)
+ To bind to a specific site in a specific cell, specify
either the site's global name (for example,
/.../r_d.com/subsys/dce/sec/rs_server_250_2) or the site's
network address (for example, ncadg_ip_udp:15.22.144.248)
auth_info
A pointer to the sec_rgy_bind_auth_info_t structure that
identifies the authentication protocol, protection level, and
authorization protocol to use in establishing the binding.
(See the rpc_binding_set_auth_info() routine). If the
sec_rgy_bind_auth_info_t structure specifies authenticated rpc,
the caller must have established a valid network identity for
this call to succeed.
Output
context
A pointer to a sec_rgy_handle_t variable. Upon return, this
contains a registry server handle indicating ("bound to") the
desired registry site.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_bind() call binds to a registry site at the security
level specified by the auth_info parameter. The site_name parameter
identifies the registry to use. If site_name is NULL, or a zero-
length string, a registry site in the local cell is selected by the
client agent.
NOTES
Like the sec_rgy_site_bind_query() routine, this routine binds
arbitrarily to either an update or query site. Although update
sites can accept queries, query sites cannot accept updates. To
specifically select an update site, use sec_rgy_site_bind_update().
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
sec_login_s_no_current_context
The caller does not have a valid network login context.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_open
sec_rgy_cell_bind
4.158 – sec_rgy_site_bind_query
NAME
sec_rgy_site_bind_query - Binds to a registry query site
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_bind_query(
unsigned_char_t *site_name,
sec_rgy_bind_auth_info_t *auth_info,
sec_rgy_handle_t *context,
error_status_t *status);
PARAMETERS
Input
site_name
A character string (type unsigned_char_t) containing the name
of the registry site to bind to. Supply this name in any of
the following forms:
+ To randomly choose a site to bind to in the named cell,
specify a cell name (for example, /.../r_d.com or /.:
for the local cell)
+ To bind to a specific site in a specific cell, specify
either the site's global name (for example,
/.../r_d.com/subsys/dce/sec/rs_server_250_2) or the site's
network address (for example, ncadg_ip_udp:15.22.144.248)
auth_info
A pointer to the sec_rgy_bind_auth_info_t structure that
identifies the authentication protocol, protection level, and
authorization protocol to use in establishing the binding.
(See the rpc_binding_set_auth_info() routine). If the
sec_rgy_bind_auth_info_t structure specifies authenticated rpc,
the caller must have established a valid network identity for
this call to succeed.
Output
context
A pointer to a sec_rgy_handle_t variable. Upon return, this
contains a registry server handle indicating ("bound to") the
desired registry site.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_bind_query() routine binds to a registry query site
at an arbitrary level of security. A registry query site is a satellite
server that operates on a periodically updated copy of the main
registry database. To change the registry database, it is necessary
to change a registry update site, which then automatically updates its
associated query sites. No changes can be made directly to a registry
query database.
The site_name parameter identifies the query site to use. If site_name
is NULL, or a zero-length string, a query site in the local cell is
selected by the client agent.
The handle for the associated registry server is returned in context.
NOTES
Like sec_rgy_bind_open() routine, this routine binds arbitrarily to
either an update or query site. Although update sites can accept
queries, query sites cannot accept updates. To specifically select
an update site, use sec_rgy_site_bind_update().
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
sec_login_s_no_current_context
The caller does not have a valid network login context.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_open
sec_rgy_site_bind
4.159 – sec_rgy_site_bind_update
NAME
sec_rgy_site_bind_update - Binds to a registry update site
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_bind_update(
unsigned_char_t *site_name,
sec_rgy_bind_auth_info_t *auth_info,
sec_rgy_handle_t *context,
error_status_t *status);
PARAMETERS
Input
site_name
A character string (type unsigned_char_t) containing the name
of the registry site to bind to. Supply this name in any of
the following forms:
+ To choose the update site to bind to in the named cell,
specify a cell name (for example, /.../r_d.com or /.:
for the local cell)
+ To start the search for the update site at a specific
replica in the replica's cell, specify either the
replica's global name (for example,
/.../r_d.com/subsys/dce/sec/rs_server_250_2) or the
replica's network address (for example,
ncadg_ip_udp:15.22.144.248)
auth_info
A pointer to the sec_rgy_bind_auth_info_t structure that
identifies the authentication protocol, protection level,
and authorization protocol to use in establishing the binding.
(See the rpc_binding_set_auth_info() routine). If the
sec_rgy_bind_auth_info_t structure specifies authenticated rpc,
the caller must have established a valid network identity for
this call to succeed.
Output
context
A pointer to a sec_rgy_handle_t variable. Upon return, this
contains a registry server handle indicating ("bound to") the
desired registry site.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_bind_update() routine binds to a registry update site.
A registry update site is a master server that may control several
satellite (query) servers. To change the registry database, it is
necessary to change a registry update site, which then automatically
updates its associated query sites. No changes can be made directly to
a registry query database.
The site_name parameter identifies either the cell in which to find
the update site or the replica at which to start the search for the
update site. If site_name is NULL, or a zero-length string, an update
site in the local cell is selected by the client agent.
The handle for the associated registry server is returned in context.
The handle is to an update site. Use this registry context handle in
subsequent calls that update or query the the registry database (for
example, the sec_rgy_pgo_add() or sec_rgy_acct_lookup() call).
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
sec_login_s_no_current_context
The caller does not have a valid network login context.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_open
sec_rgy_site_bind
sec_rgy_site_open
4.160 – sec_rgy_site_binding_get_info
NAME
sec_rgy_site_binding_get_info - Returns information from the registry
binding handle
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_binding_get_info(
sec_rgy_handle_t context,
unsigned_char_t **cell_name,
unsigned_char_t **server_name,
unsigned_char_t **string_binding,
sec_rgy_bind_auth_info_t *auth_info,
error_status_t *status);
PARAMETERS
Input
context
A sec_rgy_handle_t variable that contains a registry server
handle indicating ("bound to") the desired registry site. To
obtain information on the default binding handle, initialize
context to sec_rgy_default_handle. A valid login context must
be set for the process if context is set to
sec_rgy_default_handle; otherwise the error
sec_under_login_s_no_current_context is returned.
Output
cell_name
The name of the home cell for this registry.
server_name
The name of the node on which the server is resident. This name
is either a global name or a network address, depending on the
form in which the name was input to the call that bound to the
site.
string_binding
A string containing binding information from sec_rgy_handle_t.
auth_info
A pointer to the sec_rgy_bind_auth_info_t structure that
identifies the authentication protocol, protection level,
and authorization protocol to use in establishing the binding.
(See the rpc_binding_set_auth_info() routine).
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_binding_get_info() routine returns the site name and
authentication information associated with the context parameter. If
the context is the default context, the information for the default
binding is returned. Passing in a NULL value for any of the output
values (except for status) will prevent that value from being returned.
Memory is allocated for the string returned in the cell_name,
server_name, and string_binding parameters. The application calls the
rpc_string_free() routine to deallocate that memory.
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
sec_under_login_s_no_current_context
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_open
sec_rgy_site_bind
4.161 – sec_rgy_site_close
NAME
sec_rgy_site_close - Frees the binding handle for a registry server
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_close(
sec_rgy_handle_t context,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle indicating ("bound to") a registry server.
Use sec_rgy_site_open() to acquire a bound handle.
Output
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_close() routine frees the memory occupied by the
specified handle and destroys its binding with the registry server.
NOTES
A handle cannot be used after it is freed.
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_get
sec_rgy_site_is_readonly
sec_rgy_site_open
sec_rgy_site_open_query
sec_rgy_site_open_update
4.162 – sec_rgy_site_get
NAME
sec_rgy_site_get - Returns the string representation for a bound
registry site
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_get(
sec_rgy_handle_t context,
unsigned_char_t **site_name,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle indicating (bound to'') a registry server.
Use sec_rgy_site_open() to acquire a bound handle. To obtain
information on the default binding handle, initialize context
to sec_rgy_default_handle. A valid login context must be set
for the process if context is set to sec_rgy_default_handle;
otherwise the error sec_under_login_s_no_current_context is
returned.
Output
site_name
A pointer to a character string (type unsigned_char_t)
containing the returned name of the registry site associated
with context, the given registry server handle.
The name is either a global name or a network address,
depending on the form in which the name was input to the call
that bound to the site.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_get() routine returns the name of the registry site
associated with the specified handle. If the handle is the default
context, the routine returns the name of the default context's site.
Memory is allocated for the string returned in the site_name
parameter. The application calls the rpc_string_free() routine to
deallocate that memory.
NOTES
To obtain binding information, the use of the
sec_rgy_site_binding_get_info() call is recommended in place of this
call.
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
sec_under_login_s_no_current_context
sec_rgy_server_unavailable
The requested registry server is not available.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_open
4.163 – sec_rgy_site_is_readonly
NAME
sec_rgy_site_is_readonly - Checks whether a registry site is read-only
SYNOPSIS
#include <dce/binding.h>
boolean32 sec_rgy_site_is_readonly(
sec_rgy_handle_t context);
PARAMETERS
Input
context
An opaque handle indicating (bound to'') a registry server.
Use sec_rgy_site_open() to acquire a bound handle.
DESCRIPTION
The sec_rgy_site_is_readonly() routine checks whether the registry
site associated with the specified handle is a query site or an
update site. A query site is a read-only replica of a master registry
database. The update site accepts changes to the registry database,
and duplicates the changes in its associated query sites.
RETURN VALUES
The routine returns:
+ TRUE if the registry site is read-only or if there was an error
using the specified handle
+ FALSE if the registry site is an update site
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_open
sec_rgy_site_open_query
4.164 – sec_rgy_site_open
NAME
sec_rgy_site_open - Binds to a registry site
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_open(
unsigned_char_t *site_name,
sec_rgy_handle_t *context,
error_status_t *status);
PARAMETERS
Input
site_name
A pointer to a character string (type unsigned_char_t)
containing the name of the registry site to bind to. Supply
this name in any of the following forms:
+ To randomly choose a site to bind to in the named cell,
specify a cell name (for example, /.../r_d.com or /.: for
the local cell)
+ To bind to a specific site in a specific cell, specify either
the site's global name (for example,
/.../r_d.com/subsys/dce/sec/rs_server_250_2) or the site's
network address (for example, ncadg_ip_udp:15.22.144.248)
Note that if you specify the name of a specific secd to bind to and
the name is not valid, the call will bind to a random site in the cell
if the specified cell name is valid.
Output
context
A pointer to a sec_rgy_handle_t variable. Upon return, this
contains a registry server handle indicating ("bound to") the
desired registry site.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_open() routine binds to a registry site at the level
of security specified in the rpc_binding_set_auth_info() call. The
site_name parameter identifies the registry to use. If site_name is
NULL, or a zero-length string, a registry site in the local cell is
selected by the client agent. The caller must have established a
valid network identity for this call to succeed.
NOTES
To bind to a registry site, the use of the sec_rgy_site_bind() call is
recommended in place of this call.
Like sec_rgy_site_open_query() routine, this routine binds arbitrarily
to either an update or query site. Although update sites can accept
queries, query sites cannot accept updates. To specifically select
an update site, use sec_rgy_site_open_update().
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
sec_login_s_no_current_context
The caller does not have a valid network login context.
sec_rgy_server_unavailable
The requested registry server is not available.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_close
sec_rgy_site_is_readonly
sec_rgy_site_open_query
sec_rgy_site_open_update
4.165 – sec_rgy_site_open_query
NAME
sec_rgy_site_open_query - Binds to a registry query site
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_open_query(
unsigned_char_t *site_name,
sec_rgy_handle_t *context,
error_status_t *status);
PARAMETERS
Input
site_name
A character string (type unsigned_char_t) containing the name
of the registry query site to bind to. Supply this name in any
of the following forms:
+ To randomly choose a site to bind to in the named cell,
specify a cell name (for example, /.../r_d.com or /.:
for the local cell)
+ To bind to a specific site in a specific cell, specify
either the site's global name (for example,
/.../r_d.com/subsys/dce/sec/rs_server_250_2) or the site's
network address (for example, ncadg_ip_udp:15.22.144.248)
Output
context
A pointer to a sec_rgy_handle_t variable. Upon return, this
contains a registry server handle indicating ("bound to") the
desired registry site.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_open_query() routine binds to a registry query site.
A registry query site is a satellite server that operates on a
periodically updated copy of the main registry database. To change
the registry database, it is necessary to change a registry update
site, which then automatically updates its associated query sites.
No changes can be made directly to a registry query database.
The site_name parameter identifies the query site to use. If site_name
is NULL, or a zero-length string, a query site in the local cell is
selected by the client agent.
The handle for the associated registry server is returned in context.
The caller must have established a valid network identity for this
call to succeed.
NOTES
To bind to a registry query site, the use of the
sec_rgy_site_bind_query() call is recommended in place of this call.
Like sec_rgy_site_open() routine, this routine binds arbitrarily to
either an update or query site. Although update sites can accept
queries, query sites cannot accept updates. To specifically select
an update site, use sec_rgy_site_open_update().
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
Errors
sec_login_s_no_current_context
The caller does not have a valid network login context.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_close
sec_rgy_site_get
sec_rgy_site_is_readonly
sec_rgy_site_open
sec_rgy_site_open_update
4.166 – sec_rgy_site_open_update
NAME
sec_rgy_site_open_update - Binds to a registry update site
SYNOPSIS
#include <dce/binding.h>
void sec_rgy_site_open_update(
unsigned_char_t *site_name,
sec_rgy_handle_t *context,
error_status_t *status);
PARAMETERS
Input
site_name
A character string (type unsigned_char_t) containing the name
of an update registry site to bind to. Supply this name in
any of the following forms:
+ To choose the update site to bind to in the named cell,
specify a cell name (for example, /.../r_d.com or /.:
for the local cell)
+ To start the search for the update site at a specific
replica in the replica's cell, specify either the site's
global name (for example,
/.../r_d.com/subsys/dce/sec/rs_server_250_2) or the site's
network address (for example, ncadg_ip_udp:15.22.144.248)
Output
context
A pointer to a sec_rgy_handle_t variable. Upon return, this
contains a registry server handle indicating ("bound to") the
desired registry site.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_site_open_update() routine binds to a registry update site.
A registry update site is a master server that may control several
satellite (query) servers. To change the registry database, it is
necessary to change a registry update site, which then automatically
updates its associated query sites. No changes can be made directly to
a registry query database.
The site_name parameter identifies either the cell in which to find the
update site or the replica at which to start the search for the update
site. If site_name is NULL, or a zero-length string, an update site in
the local cell is selected by the client agent.
The handle for the associated registry server is returned in context.
The handle is to an update site. Use this registry context handle in
subsequent calls that update or query the the registry database (for
example, the sec_rgy_pgo_add() or sec_rgy_acct_lookup() call). The
caller must have established a valid network identity for this call to
succeed.
NOTES
To bind to a registry update site, the use of the
sec_rgy_site_bind_update() call is recommended in place of this call.
FILES
SYS$COMMON:[DCE$LIBRARY]BINDING.IDL
The idl file from which dce/binding.h was derived.
ERRORS
sec_login_s_no_current_context
The caller does not have a valid network login context.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
sec_rgy_site_close
sec_rgy_site_get
sec_rgy_site_is_readonly
sec_rgy_site_open
sec_rgy_site_open_query
4.167 – sec_rgy_unix_getgrgid
NAME
sec_rgy_unix_getgrgid - Returns a UNIX style group entry for the
account matching the specified group ID
SYNOPSIS
#include <dce/rgynbase.h>
void sec_rgy_unix_getgrent(
sec_rgy_handle_t context,
signed32 gid,
signed32 max_number,
sec_rgy_cursor_t *item_cursor,
sec_rgy_unix_group_t *group_entry,
signed32 *number_members,
sec_rgy_member_t member_list[],
error_status_t *status);
PARAMETERS
Input
A pointer to an opaque handle bound to a registry server.
Use sec_rgy_site_open() to acquire a bound handle.
gid
A 32-bit integer specifying the group ID to match.
max_number
The maximum number of members to be returned by the call.
This must be no larger than the allocated size of the
member_list[] array.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in
the registry database. The sec_rgy_pgo_get_next() routine
returns the PGO item indicated by item_cursor, and advances
the cursor to point to the next item in the database. When
the end of the list of entries is reached, the routine
returns sec_rgy_no_more_entries. Use
sec_rgy_cursor_reset() to refresh the cursor.
Output
group_entry
A UNIX style group entry structure returned with
information about the account matching gid.
number_members
An signed 32-bit integer containing the total number of
member names returned in the member_list[] array.
member_list[]
An array of character strings to receive the returned
member names. The size allocated for the array is given by
max_number. If this value is less than the total number of
members in the membership list, multiple calls must be made
to return all of the members.
status
On successful completion, the routine returns
error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_rgy_unix_getgrgid() routine returns the next UNIX group
structure that matches the input UNIX group ID. The structure
is in the following form:
typedef struct {
sec_rgy_name_t name;
signed32 gid;
sec_rgy_member_buf_t members;
} sec_rgy_unix_group_t;
The structure includes
o The name of the group.
o The group's UNIX ID.
o A string containing the names of the group members. This
string is limited in size by the size of the
sec_rgy_member_buf_t
type defined in rgynbase.idl.
The routine also returns an array of member names, limited in size
by the number_members parameter.
This call is supplied in source code form.
FILES
SYS$COMMON:[DCE$LIBRARY]RGYBASE.IDL
The idl file from which dce/rgybase.h was derived.
ERRORS
sec_rgy_nomore_entries
The end of the list of entries has been reached.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro.
4.168 – sec_rgy_unix_getgrnam
NAME
sec_rgy_unix_getgrnam - Returns a UNIX style group entry for the
account matching the specified group name
SYNOPSIS
#include <dce/rgynbase.h>
void sec_rgy_unix_getgrnam(
sec_rgy_handle_t context,
sec_rgy_name_t name,
signed32 name_length,
signed32 max_num_members,
sec_rgy_cursor_t item_cursor,
sec_rgy_unix_group_t group_entry,
signed32 number_members,
sec_rgy_member_t member_list[],
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name A character string (of type sec_rgy_name_t) specifying the
group name to be matched.
name_length
An signed 32-bit integer specifying the length of name in
characters.
max_num_members
The maximum number of members to be returned by the call.
This must be no larger than the allocated size of the
member_list[] array.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in the
registry database. The sec_rgy_unix_getgrnam() routine returns
the PGO item indicated by item_cursor, and advances the cursor
to point to the next item in the database. When the end of the
list of entries is reached, the routine returns
sec_rgy_no_more_entries. Use sec_rgy_cursor_reset() to refresh
the cursor.
Output
group_entry
A UNIX style group entry structure returned with information
about the account matching name.
number_members
An signed 32-bit integer containing the total number of member
names returned in the member_list[] array.
member_list[]
An array of character strings to receive the returned member
names. The size allocated for the array is given by max_number.
If this value is less than the total number of members in the
membership list, multiple calls must be made to return all of
the members.
status
On successful completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The sec_rgy_unix_getgrnam() routine looks up the next group entry in
the registry that matches the input group name and returns the
corresponding UNIX style group structure. The structure is in the
following form:
typedef struct {
sec_rgy_name_t name;
signed32 gid;
sec_rgy_member_buf_t members;
} sec_rgy_unix_group_t;
The structure includes
+ The name of the group.
+ The group's UNIX ID.
+ A string containing the names of the group members. This string
is limited in size by the size of the sec_rgy_member_buf_t type
defined in rgynbase.idl.
The routine also returns an array of member names, limited in size
by the number_members parameter. Note that the array contains only
the names explicitly specified as members of the group. A principal
that was made a member of the group because that group was assigned
as the principal's primary group will not appear in the array.
This call is provided in source code form.
FILES
SYS$COMMON:[DCE$LIBRARY]RGYBASE.IDL
The idl file from which dce/rgybase.h was derived.
ERRORS
sec_rgy_no_more_entries
The end of the list of entries has been reached.
sec_rgy bad_data
The name supplied as input was too long.
error_status_ok
The call was successful.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
RELATED INFORMATION
Functions: sec_intro
4.169 – sec_rgy_unix_getpwnam
NAME
sec_rgy_unix_getpwnam - Returns a UNIX style passwd entry for account
matching the specified name.
SYNOPSIS
#include <dce/rgynbase.h>
void sec_rgy_unix_getpwnam (
sec_rgy_handle_t context,
sec_rgy_name_t name,
unsigned32 name_len,
sec_rgy_cursor_t *item_cursor,
sec_rgy_unix_passwd_t *passwd_entry,
error_status_t *status);
PARAMETERS
Input
context An opaque handle bound to a registry server. Use
sec_rgy_site_open to acquire a bound handle.
name A character string (of type sec_rgy_name_t) containing the
name of the person, group, or organization whose name entry
is desired.
name_len A 32-bit integer representing the length of the name in
characters.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in
the registry database. The sec_rgy_unix_getpwnam routine
returns the PGO item indicated by item_cursor, and advances
the cursor to point to the next item in the database. When
the end of the list of entries is reached, the routine
returns sec_rgy_no_more_entries. Use sec_rgy_cursor_reset
to refresh the cursor.
Output
passwd_entry
A UNIX style passwd structure returned with information
about the account matching name.
status On successful completion, the routine returns
error_status_ok. Otherwise, it returns an error.
DESCRIPTION
The sec_rgy_unix_getpwnam routine returns the next UNIX passwd
structure that matches the input name. The structure is in the form:
typedef struct {
sec_rgy_unix_login_name_t name;
sec_rgy_unix_passwd_buf_t passwd;
signed32 uid;
signed32 gid;
signed32 oid;
sec_rgy_unix_gecos_t gecos;
sec_rgy_pname_t homedir;
sec_rgy_pname_t shell;
} sec_rgy_unix_passwd_t;
The structure includes:
+ The account's login name.
+ The account's password.
+ The account's UNIX ID.
+ The UNIX ID of group and organization associated with the
account.
+ The account's GECOS information.
+ The account's home directory.
+ The account's login shell
This call is provided in source code form.
FILES
SYS$COMMON:[DCE$LIBRARY]RGYNBASE.IDL
The idl file from which rgynbase.h was derived.
ERRORS
sec_rgy bad_data
The name supplied as input was too long.
error_status_ok
The call was successful.
sec_rgy_no_more_entries
The end of the list of entries has been reached.
RELATED INFORMATION
Functions: sec_intro
4.170 – sec_rgy_unix_getpwuid
NAME
sec_rgy_unix_getpwuid - Returns a UNIX style passwd entry for
the account matching the specified UID
SYNOPSIS
#include <dce/rgynbase.h>
void sec_rgy_unix_getpwuid(
sec_rgy_handle_t context,
signed32 uid,
sec_rgy_cursor_t *item_cursor,
sec_rgy_unix_passwd_t *passwd_entry,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
uid A 32-bit integer UNIX ID.
Input/Output
item_cursor
An opaque pointer indicating a specific PGO item entry in the
registry database. The sec_rgy_unix_getpwuid() routine returns
the PGO item indicated by item_cursor, and advances the cursor
to point to the next item in the database. When the end of the
list of entries is reached, the routine returns
sec_rgy_no_more_entries. Use sec_rgy_cursor_reset() to refresh
the cursor.
Output
passwd_entry
A UNIX style password structure returned with information
about the account matching uid.
status
On successful completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The sec_rgy_unix_getpwuid() routine looks up the next passwd entry
in the registry that matches the input UNIX ID and returns the
corresponding sec_rgy_passwd structure. The structure is in the
following form:
typedef struct {
sec_rgy_unix_login_name_t name;
sec_rgy_unix_passwd_buf_t passwd;
signed32 Vuid;
signed32 Vgid;
signed32 oid;
sec_rgy_unix_gecos_t gecos;
sec_rgy_pname_t homedir;
sec_rgy_pname_t shell;
} sec_rgy_unix_passwd_t;
The structure includes
+ The account's login name.
+ The account's password.
+ The account's UNIX ID.
+ The UNIX ID of group and organization associated with the
account.
+ The account's GECOS information.
+ The account's home directory.
+ The account's login shell
FILES
SYS$COMMON:[DCE$LIBRARY]RGYNBASE.IDL
The idl file from which dce/rgynbase.h was derived.
This call is provided in source code form.
ERRORS
sec_rgy_no_more_entries
The end of the list of entries has been reached.
sec_rgy_server_unavailable
The DCE Registry Server is unavailable.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro
4.171 – sec_rgy_wait_until_consistent
NAME
sec_rgy_wait_until_consistent - Blocks the caller while prior
updates are propagated to the
registry replicas
SYNOPSIS
#include <dce/misc.h>
boolean32 sec_rgy_wait_until_consistent(
sec_rgy_handle_t context,
error_status_t *status);
PARAMETERS
Input
context
The registry server handle associated with the master registry.
Output
status
A pointer to the completion status. On successful completion,
status is assigned error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_wait_until_consistent() routine blocks callers until all
prior updates to the master registry have been propagated to all
active registry replicas.
RETURN VALUES
The routine returns TRUE when all active replicas have received the
prior updates. It returns FALSE if at least one replica did not
receive the updates.
FILES
SYS$COMMON:[DCE$LIBRARY]MISC.IDL
The idl file from which dce/misc.h was derived.
ERRORS
sec_rgy_server_unavailable
The server for the master registry is not available.
sec_rgy_read_only
Either the master site is in maintenance mode or the
site associated with the handle is a read-only (query)
site.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: sec_intro