6 — Samples

[Previous] [Next] [Contents] [Index]

6.1 Using the Sample Applications

PC-DCE provides the following sample programs to introduce you to DCE programming and to test the integrity of your PC-DCE installation and configuration:

• Greet Application (Section 6.2.1)
  
• Grade Application (Section 6.2.2)
  

The Greet sample application consists of the following programs:

• client.exe — Greet Client program
  
• server.exe — Greet Server program
  

The Greet application is implemented as a 32-bit Windows application. The executable files for the Greet application (client.exe and server.exe) are located in dce_install_directory\samples\greet and appear as icons (Greet Client and Greet Server) in the PC-DCE program group. You can run these programs after installation and configuration, or at any time to verify that PC-DCE is operating properly.

The Greet application provides a simple way for you to demonstrate how pthreads, CDS, and RPC can be used to accomplish the following tasks:

• Advertise the existence of a remote server to a client

• Locate a remote server

• Establish a connection between a client and server

• Exchange a handshake (or greeting message) between a client and server

You can run the Greet client and server programs on the same system, or run one of the programs on your local PC and the other program on a remote system.

6.2.1 The Greet Client

The Greet client program supports three different methods of locating the Greet server:

• Use string binding

  Locates a Greet server by specifying the exact network location of the target server using a DNS name or an IP address.

• Import bindings from CDS

  Locates the server(s) registered in the CDS namespace via the cdsclerk process in the DCE DLL.

• Use local server

  Locates the server by communicating with dced and restricting the search to the local system.

Entegrity suggests that you try running the Greet client using the string binding first, then local server, and finally by looking up server locations in the CDS namespace.

6.2.2 The Greet Server

The Greet server program advertises its existence to dced only, or to both dced and CDS. Registration with dced only allows the Greet client to establish a connection by using string bindings or a local server. However, registration with CDS enables the Greet client to locate the server without knowing the location of the system where the Greet server is running. Again, Entegrity suggests that you try the simple case first by disabling registration of the Greet server's bindings in the CDS namespace.

6.2.3 Running the Greet Sample Programs

1. For the Greet application to work properly, dced and the CDS Advertiser (cdsadv) must be running on your system. If in doubt, select the PC-DCE icon in the Windows Control Panel to activate the PC-DCE Service Panel and verify that the Remote Procedure Call daemon and the CDS Advertiser are running.

2. If not already logged in, DCE_login to your cell, using a valid principal and password.

   To log in, open an MS-DOS window and type: dce_login. Then enter your username and password.

3. Select the Greet Server icon from the PC-DCE program group to start the Greet server program. The Greet Server dialog appears. The Server name field displays the predefined CDS name for your Greet server (/.:/hosts/yourhostname/greet-server) that was created as part of the PC-DCE configuration on your system.

4. In the Threads dialog box, specify how many threads you want the Greet server to use when listening for Greet client communications.

5. By default, the checkbox Export Server Binding into CDS is marked with an X to allow Greet clients to establish a connection with the server by performing a name lookup in the CDS namespace. If you want Greet clients to connect with their local Greet server, or to establish a connection with this server only by using a string binding, deselect the checkbox Export Server Binding into CDS.

6. When satisfied with your settings, click Start. The Greet server responds by registering itself with dced and with CDS (if you accepted the default in the checkbox Export Server Bindings into CDS in step 5).

   The RPC registration process may take a few moments. When the server is ready to receive client calls, it prints Listening... in the Output: box.

7. Select the Greet Client icon from the PC-DCE program group to start the Greet client program. The Greet Client Sample Program dialog appears.

8. Click the appropriate radio button to select the method by which the Greet Client will locate a Greet Server:
   • Select Use Local Server to restrict a search for a Greet server by dced to your local system.

   • Select Import Bindings from CDS to instruct the client to look up the location of the Greet server in the CDS namespace.

   • Select Use String Binding to Server to locate the server by the information provided in the string binding.

9. In the Message To Send field, enter the message that you want to send to the Greet server. The message Hello Server is specified by default.

10. In the Repetitions field, enter the number of times you want the Greet client to send the message that you specified. By default, the client repeats the message 5 times.

11. When satisfied with your settings, click Send. The client imports the server's binding handle (if CDS is selected) and exchanges messages with the server. The server prints the client's greeting message and the client prints the server's default reply Hi client!.

NOTE: If you directed the Greet client to look up the location of a Greet server in the CDS namespace and if there are multiple Greet servers (of the same name) active in your cell, you will be unable to control with which servers the Greet client actually connects. This is because, based on identical names, the Greet client binds randomly to a Greet server via CDS. You can alter this behavior by using RPC profiles or by specifying unique server names.

To cancel either program, click the Cancel button. When you cancel the Greet server, it automatically unregisters its endpoint.

6.3 Grade Application

The Grade sample application consists of the following programs:

• client.exe — Grade Server client program
  
• server.exe — Grade Server server program
  

The Grade Server application is implemented as a Windows Console application to demonstrate how you can create standard UNIX-style client and server programs in the Win32® environment and avoid the overhead of creating a Windows GUI. The executable files for the Grade Server application (client.exe and server.exe) are located in dce_install_directory \samples\grade.

The Grade Server programs shipped with PC-DCE are implemented as Windows Console applications. They are based on the UNIX Grade Server application that appears in the second edition of the Guide to Writing DCE Applications (Shirley, Hu, and Magid) published by O'Reilly & Associates, Inc. Entegrity's adaptations of these programs demonstrate how easy it is to modify an existing DCE application to run under Windows. (Setup instructions for this application were derived, in part, from materials provided by O'Reilly & Associates, Inc.)

The server stores a fixed database of student names and their grade point averages (GPAs). The client queries the database for GPA information and the Grade server responds to the client.

The only interface defined for the server is the GPA interface that is called by the client. This remote procedure returns the GPA associated with individual students.

The Grade Server application illustrates the use of authenticated RPC and DCE Security services, including the following tasks:

• Annotating a binding for authenticated RPC.
  
• Determining a server's principal name.
  
• Setting up a server's login context.
  
• Creating a thread to manage a server's secret key.
  
• Setting up a reference monitor that uses name and group membership for authorization.
  

The implementation of the Grade Server assumes that the principal identities and groups and the keytab file have been created and that the keytab file can be accessed by the Grade Server process. It also assumes that the server can export to CDS. You perform these operations using the management utilities supplied with PC-DCE. You should perform the Security setup first to create the principal identities required for the CDS operation.

6.3.1.1 Security Setup

The implementation assumes that the Grade server process executes with the local identity of grade_server_1. The server process needs a local identity so that it can access its keytab file.

Before you can run the Grade Server application, you need to use dcecp to perform the following tasks:

• Create groups for both the Grade servers and teachers. (Note that the grade_server group is not used by the server; it is used by clients to authenticate the server.)

• Create principals for the Grade server, students, and teachers.

• Create accounts for each of the three principals.

• Create a keytab file for the server.

1. Invoke the DCE Login utility and enter the following command to log in as the cell administrator:

   dce_login cell_admin cell_admin_password
   

2. Invoke dcecp and enter the following commands to create the grade_server, student, and teacher groups:

   dcecp> group create grade_server
   

   dcecp> group create teacher
   

3. Create the grade_server_1, student_1, and teacher_1 principals.

   dcecp> principal create grade_server_1
   

   dcecp> principal create student_1
   

   dcecp> principal create teacher_1
   

4. Add the grade_server_1, student_1, and teacher_1 principals to their appropriate groups:

   dcecp> group add grade_server -m grade_server_1
   

   dcecp> group add none -m student_1
   

   dcecp> group add teacher -m teacher_1
   

5. Add the grade_server_1, student_1, and teacher_1 principals to their appropriate organizations:

   dcecp> org add none -m grade_server_1
   

   dcecp> org add none -m student_1
   

   dcecp> org add none -m teacher_1
   

6. Create accounts for the three principals. Make grade_server_1 a member of the grade_server group, student_1 a member of the student group, and teacher_1 a member of the teacher group.

   dcecp> account create grade_server_1 -group grade_server -o none -pa 
   -dce- -my cell_admin_password
   

   dcecp> account create student_1 -group none -o none -pa -dce- -my 
   cell_admin_password
   

   dcecp> account create teacher_1 -group teacher -o none -pa -dce- -my 
   cell_admin_password
   

7. Create a keytab file for the grade_server_1 principal. The following command must be executed on the system where you intend to run the Grade Server program. In addition, replace server_host_name below with the name of your host server. Note that you must also create the /tmp directory if it doesn't already exist.

   dcecp> keytab create \
   /.:/hosts/server_host_name/config/keytab/grade_server_1 -storage \
   "/tmp/grade_server_tab" -data {grade_server_1 plain 1 -dce-} 
   

Perform the following steps to create a CDS object (/.:/grade) and modify its ACL:

1. Enter the following command to create the object in CDS. This is the entry to which the Grade Server exports its bindings.

   dcecp> obj create /.:/grade
   

2. Modify the ACL to grant read and write access to the grade_server_1 principal.

   dcecp> acl modify -e /.:/grade -add {user grade_server_1 rw}
   

3. Issue the following command to verify that the grade_server_1 principal is granted the correct permissions.

   dcecp> acl show -e /.:/grade -entry
   

   {unauthenticated:r--t-}
   {user:cell_admin:rwdtc}
   {user:grade_server_1:rw---}
   {group:subsys/dce/cds-admin:rwdtc}
   {group:subsys/dce/cds-server:rwdtc}
   {any_other:r--t-}
   

   dcecp> exit
   

At this point, you are ready to run the application. Begin by starting up the Grade Server. Because the server will establish its own DCE identity, the process that starts the Grade Server does not need to log into DCE.

6.3.2.1 Running the Grade Server Program

To start the Grade Server, change directories to dce_install_directory \samples\grade and enter the server command.

6.3.2.2 Running the Grade Client Program

1. Invoke the DCElogin utility and DCElogin as the student_1 principal. If you've been following the instructions presented above, keep in mind that the assigned password is -dce-.

2. Change directories to dce_install_directory\samples\grade. To start the Grade Client and display the GPA for student_1, enter client student_1. The GPA for student_1 is displayed.

3. Now enter client Peter to attempt to retrieve the GPA for the student Peter. Because you are logged in as student_1, and you are not a teacher, your query is not permitted and the server returns a GPA of -1.00000.

4. Repeat step 1, but this time, login as the teacher_1 principal. Then repeat step 2 to prove that the teacher_1 principal is permitted to retrieve the GPA for student_1.

5. Repeat step 3. This time, because you are logged in as teacher_1, you are entitled to see all GPAs in the database and the Grade Server displays Peter's GPA, 4.00000.

[Previous] [Next] [Contents] [Index]

To make comments or ask for help, contact support@entegrity.com.

Copyright © 1997-2003 Entegrity Solutions Corporation & its subsidiaries