#
# @(#)76	1.5  src/examples/acl_mgr/readme, examples.src, os2dce21.dss, 960602a.1  5/12/96  06:36:25
#
# COMPONENT_NAME:  examples.src
#
# FUNCTIONS: readme file for acl_mgr application example
#
# ORIGINS: 72/27
#
# (C) COPYRIGHT International Business Machines Corp. 1995
#  All Rights Reserved
#  Licensed Materials - Property of IBM
#
#  US Government Users Restricted Rights - Use, duplication or
#  disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
#
# @OSF_COPYRIGHT@
# COPYRIGHT NOTICE
# Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc.
# ALL RIGHTS RESERVED (DCE).  See the file named COPYRIGHT.DCE in the
# src directory for the full copyright text.
#
#
------------------------------------------------------------------------------
------------------------------------------------------------------------------

Directory:

   opt\dcelocal\examples\acl_mgr


This directory contains the source code for a sample acl mgr DCE client/server
application. This application consists almost entirely of initialization and
cleanup code, including extensive examples of ACL management and security
setup. The actual manager code consists of one generic remote call that does
no actual work, but which does make use of the ACL manager.

The following files are contained in this directory:

    makefile.os2
    makefile.vc3
    makefile.bor
    makefile.wat
    readme (this file)
    acl.acf
    acl.idl
    acl_bind.acf
    acl_bind.c
    acl_bind.idl
    acl_client.c
    acl_client.def
    acl_db.acf
    acl_db.idl
    acl_rpc_server.c
    acl_mgr_setup.dcecp
    acl_mgr_unsetup.dcecp
    acl_server.c
    acl_server.h
    acl_server.def
    server_objs.bor


------------------------------------------------------------------------------

		    BUILDING THE ACL_MGR SAMPLE APPLICATION

Refer to the main Examples Readme file in opt\dcelocal\examples
for information on how to build this example.


------------------------------------------------------------------------------

		     SETTING UP TO RUN ACL_MGR SAMPLE


Before you can run acl_mgr sample, you must first setup your DCE cell with the
necessary security registry and namespace information for the program and
its client and server principal entities. You must also setup an authenti-
cation key table file on each of the machines on which you intend to run the
server. These tasks consist of the following steps:


  1. Adding the client and server principals and server group to the Security
     registry.

  2. Creating a keyfile to be used by the server.

  3. Creating a CDS namespace entry for the server to export its binding
     information to (and for the clients to import binding information from).

  4. Setting up the correct permissions on the namespace entry to allow the
     server to use it (i.e., write to it) correctly.

A pair of dcecp scripts have been included which, when run will automatically
take care of doing (or undoing) all of the above steps.


Note: the dcecp setup script assumes that the acl_mgr example will be run
      in a dce cell with a protection level of DES encryption or CDMF.
      If this is not the case, please comment out the following lines from
      the dcecp setup script:
	  puts "Creating keytab."
	  puts "keytab create aclmgr -storage  {/tmp/aclkeyfile}
		-data {acl_server plain  abcde}"
	  run_cmd {keytab create aclmgr -storage  {/tmp/aclkeyfile}
		-data {acl_server plain 1 abcde}}
      After running the dcecp setup script, create the keytab file using the
      ktadd command in rgy_edit, i.e.
	  dcelogin cell_admin -dce-
	  rgy_edit
	  ktadd -p acl_server -pw abcde -f /tmp/aclkeyfile

The name of the server's keyfile, /tmp/aclkeyfile, is specified by the value
of the KEYTAB constant in the acl_server.h file; the name you give to the
keytab create sub-command must be identical to the value of this constant.

Of course, you can substitute any legal CDS name for acl_exmp.


The following examples show how to run the setup scripts:

# dcecp acl_mgr_setup.dcecp
Usage: dcecp acl_mgr_setup.dcecp <cdsentry> -p <cell_admin passwd>

# dcecp acl_mgr_setup.dcecp /.:/acl_exmp -p -dce-

Logging in...
Creating group.
group create {acl_servers}
Creating principals.
principal create {acl_server acl_client}
Add principals to group.
group add acl_servers -member acl_server
group add none -member acl_client
Add principals to organization.
organization add none -member acl_server
organization add none -member acl_client
Creating accounts.
account create acl_server -group acl_servers -organization none -password abcde -mypwd -dce-
account create acl_client -group none -organization none -password jklmn -mypwd -dce-
Adding CDS entries.
directory create /.:/acl_exmp
rpcentry create /.:/acl_exmp/acl_server_entry
acl modify /.:/acl_exmp/acl_server_entry  -entry -add user:acl_server:rwdtc
Logging out.
Creating keytab.
keytab create aclmgr -storage {/tmp/aclkeyfile} -data {acl_server plain 1 abcde}



To undo the setup, you can run the unsetup script, as shown in the following
examples:

# dcecp acl_mgr_unsetup.dcecp
Usage:dcecp acl_mgr_unsetup.dcecp <cdsentry> -p <cell_admin passwd>

# dcecp acl_mgr_unsetup.dcecp /.:/acl_exmp -p -dce-
Logging in...
Deleting group.
group delete {acl_servers}
Deleting principals and accounts.
principal delete {acl_server}
principal delete {acl_client}
Deleting CDS entries.
rpcentry delete /.:/acl_exmp/acl_server_entry
directory delete /.:/acl_exmp
Logging out.
Deleting keytab file.
keytab delete aclmgr


For further information about dcecp, see the IBM DCE Administration Guide --
Core Components, the IBM DCE Administration Reference, and the IBM DCE User's
Guide and Reference.

You have now finished the sample acl_mgr setup.

------------------------------------------------------------------------------
		     RUNNING THE ACL_MGR SAMPLE


The server is invoked as follows (do not type this command until you have
read all this section):

    acl_server <principal_name> <CDS_dir_name>/

(NOTE THE SLASH!)

where:

    principal_name   is the server's principal name; there has to be
		     an account in the registry for this principal in
		     order for the program to be run successfully. Note
		     that this name is not specified anywhere in the
		     program source; it is determined solely by the user,
		     who must make sure that the name he specifies here is
		     the same as the one he set up in the registry.

    CDS_dir_name     is the full name (terminated by a "/") of the CDS
		     directory in which the server's namespace entry is
		     to be located; this is where the bindings are exported
		     to. Note that this argument is NOT the name of the ser-
		     ver entry; that is determined by the value of the con-
		     stant DEFNAME, defined in acl_server.c: the entry is
		     created in this directory.


Note that BEFORE YOU RUN THE SERVER you must create in the local directory
a subdirectory called "db_sample_acl"; this is where the sample application's
backing store database files will be created. The pathname to these files is
determined by the value of the ACL_DB_PATH constant at the top of the
acl_server.c file; you can change this value if you wish.

     md db_sample_acl


For example (with setup done as described in first section):

     acl_server acl_server /.:/acl_exmp/


The server will display:

acl_mgr_server: Starting up . . .
acl_mgr_server: Listening for calls . . .


------------------------------------------------------------------------------


The client is invoked as follows (do not type this command until you've read
all this section):

    acl_client <object_name>

where:

    object_name      is the name of the object you want the client to bind
		     to. Note that this is not the entry name of some export-
		     ed entity; it is some object managed by the server and
		     held in a backing store. However, the object name should
		     be expressed as a full CDS name qualified by the full
		     server entry name; that is, the object should be express-
		     ed as if the server entry were a directory, and the ob-
		     ject an entry within that directory. The alternative is
		     to just give the simple object name; if you do that, the
		     client will try to bind through the RPC_DEFAULT_ENTRY
		     value, whatever that is (or isn't).

		     If you do give the overqualified object name, then the
		     client will bind to the object through the server junc-
		     tion, as described below in the comments to
		     do_client_command_line() in sample_client.c


Note also that you must be dcelogin'd as the Cell Administrator (cell_admin)
in order for the client to be able to be properly allowed to do what it needs
to do. This is because the only principal who is given any meaningful permis-
sions on the objects managed by the application are their owner, and this is
defined at the top of acl_client.c to be cell_admin.

    dcelogin cell_admin -dce-

    set RPC_DEFAULT_ENTRY=/.:/acl_exmp/acl_server_entry


Now you can try any of the following three command forms (since at present
there are only two objects set up by the server):


    acl_client /.:/acl_exmp/acl_server_entry/sample_object


to bind to the sample object and view its contents, or:


    acl_client /.:/acl_exmp/acl_server_entry/server_mgmt


to bind via the junction to the mgmt object and view its contents, or:


    acl_client kill


to stop the acl_mgr server.

------------------------------------------------------------------------------

		 WHAT THE ACL_MGR SAMPLE APPLICATION DOES


There are two modes for running the client: you can either specify that
the server be killed, or you can specify a single object to bind to. The
object name is specified by a namespace pathname, but neither of the two
possible objects is a namespace entry. Instead, the sample application
implements a "junction" located at its server entry in the namespace, and
clients bind to objects through this junction.

Essentially this happens as follows. The client tries to bind to the over-
qualified CDS entry formed by concatenating the specified object name to the
server entry name; instead, it ends up getting a partial binding to the
server. It then makes a call to the remote bind operation with that bind-
ing, ostensibly to get the object UUID of the object whose name was specified
(to bind to) when the client was invoked. These objects are held in a backing
store database. The remote call makes its way by the familiar procedure to the
server; the application's name_to_object() routine (defined in sample_bind.c)
then simply looks up the desired object UUID by accessing the name-indexed
backing store. When the remote call completes, the client finds itself with a
full binding and the desired object UUID.



------------------------------------------------------------------------------
			   Using acl_edit

With the acl_server running, you can also access the server's ACL managers
using acl_edit. For example:

    acl_edit /.:/acl_exmp/acl_server_entry/sample_object

should get you bound to the sample_object ACL:

    sec_acl_edit>

You should now be able to list the contents of the ACL:

    sec_acl_edit> l

    # SEC_ACL for /.:/acl_exmp/acl_server_entry/sample_object:
    # Default cell = /.../<your_cellname>
    unauthenticated:r---t-
    user:cell_admin:rwdctx
    any_other:r---t-


The same commands can be used to bind to and list the contents of the
server_mgmt ACL.

For further information on acl_edit, see the IBM DCE Command Reference


------------------------------------------------------------------------------

				NOTES


A detailed explanation of the operation of the ACL management code can
be found in the IBM DCE Application Development Guide -- Introduction
and Style Guide.

For further information on the new DCE 1.1 dced facilities, see
the IBM DCE Application Development Guide; the IBM DCE Application
Development Guide -- Introduction and Style Guide; and the RPC part of
the IBM DCE Application Development Guide -- Core Components volume.

------------------------------------------------------------------------------

				SERVER OUTPUT


acl_mgr_server: Starting up . . .
acl_mgr_server: Listening for calls . . .
acl_mgr_server: AUTHORIZED
acl_mgr_server: AUTHORIZED
acl_mgr_server: AUTHORIZED


------------------------------------------------------------------------------

				CLIENT OUTPUT

------------------------------------------------------------------------------


---> acl_client  /.:/acl_exmp/acl_server_entry/sample_object

acl_client: Entering do_client_command_line()...
acl_client: Remote call option selected.
acl_client: objectname_vector->name == /.:/acl_exmp/acl_server_entry/sample_object
acl_client: Calling rpc_ns_binding_import_begin()...
acl_client: Calling rpc_ns_binding_import_next()...
acl_client: Calling rpc_ns_binding_import_done()...
acl_client: Calling rpc_ep_resolve_binding()...
acl_client: Calling rpc_binding_to_string_binding()...
acl_client: Imported resolved binding == bb9d7801-abc5-11cf-ada3-000233002a1b@ncadg_ip_udp:9.3.45.83[1570]
acl_client: Calling rpc_string_free()...
acl_client: Calling rpc_mgmt_inq_server_princ_name()...
acl_client: Principal name returned == /.../examcell/acl_server
acl_client: Calling is_valid_principal()...
acl_client: Entering is_valid_principal()...
acl_client: Initial principal name == /.../examcell/acl_server
acl_client: Initial group name     == acl_servers
acl_client: Calling dce_cf_get_cell_name()...
acl_client: Calling sec_rgy_site_open()...
acl_client: Calling sec_id_parse_name()...
acl_client: Full principal name  == /.../examcell/acl_server
acl_client: Local principal name == acl_server
acl_client: Calling sec_rgy_pgo_is_member()...
acl_client: Calling rpc_binding_set_auth_info()...
acl_client: Remote call option enacted...
acl_client: Preparing to bind to object /.:/acl_exmp/acl_server_entry/sample_object
acl_client: Calling bind_to_object()...
acl_client: Entering bind_to_object()...
acl_client: Object name == /.:/acl_exmp/acl_server_entry/sample_object
acl_client: Calling rpc_ns_entry_inq_resolution()...
acl_client: Binding to resolved name...
acl_client: Calling rpc_ns_binding_import_begin()...
acl_client: Calling rpc_ns_binding_import_next()...
acl_client: Calling rpc_ns_binding_import_done()...
acl_client: Imported partial binding.
acl_client: Calling rpc_ns_binding_inq_entry_name()...
acl_client: Calling [remote] rs_bind_to_object()...
acl_client: Fully bound to object.
acl_client: Calling rpc_string_free()...
View object /.:/acl_exmp/acl_server_entry/sample_object:
     Via junction: /.../examcell/acl_exmp/acl_server_entry
     Object name: sample_object
acl_client: Calling rpc_binding_to_string_binding()...
     Binding: bb9d7801-abc5-11cf-ada3-000233002a1b@ncacn_ip_tcp:9.3.45.83[1216]
acl_client: Calling uuid_to_string()...
     Manager Type UUID: 023fb458-0000-0001-0000-02004cfa0f01
acl_client: Calling uuid_to_string()...
     Object UUID: d56f71da-a012-11ce-92fb-000000806635
acl_client: Calling [remote] sample_get_text()...
     Object Text: THIS IS AN OFFICIAL SAMPLE OBJECT TEXT!
acl_client: Calling rpc_binding_to_string_binding()...
acl_client: Binding about to be used == ncadg_ip_udp:9.3.45.83[1570]
acl_client: Calling [remote] sample_call()...
acl_client: Remote call option successfully completed.

acl_client: Calling rpc_string_free()...


******************************************************************************


---> acl_client  /.:/acl_exmp/acl_server_entry/server_mgmt

acl_client: Entering do_client_command_line()...
acl_client: Remote call option selected.
acl_client: objectname_vector->name == /.:/acl_exmp/acl_server_entry/server_mgmt
acl_client: Calling rpc_ns_binding_import_begin()...
acl_client: Calling rpc_ns_binding_import_next()...
acl_client: Calling rpc_ns_binding_import_done()...
acl_client: Calling rpc_ep_resolve_binding()...
acl_client: Calling rpc_binding_to_string_binding()...
acl_client: Imported resolved binding == bb9d7801-abc5-11cf-ada3-000233002a1b@ncacn_ip_tcp:9.3.45.83[1216]
acl_client: Calling rpc_string_free()...
acl_client: Calling rpc_mgmt_inq_server_princ_name()...
acl_client: Principal name returned == /.../examcell/acl_server
acl_client: Calling is_valid_principal()...
acl_client: Entering is_valid_principal()...
acl_client: Initial principal name == /.../examcell/acl_server
acl_client: Initial group name     == acl_servers
acl_client: Calling dce_cf_get_cell_name()...
acl_client: Calling sec_rgy_site_open()...
acl_client: Calling sec_id_parse_name()...
acl_client: Full principal name  == /.../examcell/acl_server
acl_client: Local principal name == acl_server
acl_client: Calling sec_rgy_pgo_is_member()...
acl_client: Calling rpc_binding_set_auth_info()...
acl_client: Remote call option enacted...
acl_client: Preparing to bind to object /.:/acl_exmp/acl_server_entry/server_mgmt
acl_client: Calling bind_to_object()...
acl_client: Entering bind_to_object()...
acl_client: Object name == /.:/acl_exmp/acl_server_entry/server_mgmt
acl_client: Calling rpc_ns_entry_inq_resolution()...
acl_client: Binding to resolved name...
acl_client: Calling rpc_ns_binding_import_begin()...
acl_client: Calling rpc_ns_binding_import_next()...
acl_client: Calling rpc_ns_binding_import_done()...
acl_client: Imported partial binding.
acl_client: Calling rpc_ns_binding_inq_entry_name()...
acl_client: Calling [remote] rs_bind_to_object()...
acl_client: Fully bound to object.
acl_client: Calling rpc_string_free()...
View object /.:/acl_exmp/acl_server_entry/server_mgmt:
     Via junction: /.../examcell/acl_exmp/acl_server_entry
     Object name: server_mgmt
acl_client: Calling rpc_binding_to_string_binding()...
     Binding: bb9d7801-abc5-11cf-ada3-000233002a1b@ncacn_ip_tcp:9.3.45.83[1216]
acl_client: Calling uuid_to_string()...
     Manager Type UUID: 023f1d18-0000-0001-0000-02004cfa0f01
acl_client: Calling uuid_to_string()...
     Object UUID: 7fa5f1fc-a012-11ce-b213-000000806635
acl_client: Calling [remote] sample_get_text()...
     Object Text: THIS IS AN OFFICIAL MGMT OBJECT SAMPLE TEXT!
acl_client: Calling rpc_binding_to_string_binding()...
acl_client: Binding about to be used == ncacn_ip_tcp:9.3.45.83[1216]
acl_client: Calling [remote] sample_call()...
acl_client: Remote call option successfully completed.

acl_client: Calling rpc_string_free()...

******************************************************************************


---> acl_client kill

acl_client: Entering do_client_command_line()...
acl_client: Kill server option selected.
acl_client: Calling rpc_ns_binding_import_begin()...
acl_client: Calling rpc_ns_binding_import_next()...
acl_client: Calling rpc_ns_binding_import_done()...
acl_client: Calling rpc_ep_resolve_binding()...
acl_client: Calling rpc_binding_to_string_binding()...
acl_client: Imported resolved binding == d6200ce1-abc7-11cf-9524-000233002a1b@ncadg_ip_udp:9.3.45.83[1589]
acl_client: Calling rpc_string_free()...
acl_client: Calling rpc_mgmt_inq_server_princ_name()...
acl_client: Principal name returned == /.../examcell/acl_server
acl_client: Calling is_valid_principal()...
acl_client: Entering is_valid_principal()...
acl_client: Initial principal name == /.../examcell/acl_server
acl_client: Initial group name     == acl_servers
acl_client: Calling dce_cf_get_cell_name()...
acl_client: Calling sec_rgy_site_open()...
acl_client: Calling sec_id_parse_name()...
acl_client: Full principal name  == /.../examcell/acl_server
acl_client: Local principal name == acl_server
acl_client: Calling sec_rgy_pgo_is_member()...
acl_client: Calling rpc_binding_set_auth_info()...
acl_client: Kill server option enacted...
acl_client: Calling rpc_ep_resolve_binding()...
acl_client: Calling rpc_mgmt_stop_server_listening()...
acl_client: Server successfully killed.

acl_client: Calling rpc_string_free()...

------------------------------------------------------------------------------
