Beginning with OpenVMS Alpha Version 7.2, RPC provides WINNT as an additional authentication service. WINNT, which is based on Microsoft's NTLM authentication protocol, allows you to build RPC client or server applications using WINNT authentication. These applications will allow secure communications in a Microsoft security environment.

5.1 Using WINNT Authentication with RPC Server Applications

To accept requests that use WINNT authentication, the RPC server application must do the following:

1. The server application must call rpc_server_register_auth_info() to tell the server RPC runtime that it supports WINNT authentication.
2. When the server application is run, it uses all WINNT security information from the current address space. If the process that deploys the server application has not acquired WINNT security information for its address space, then the RPC server's call to rpc_server_register_auth_info() will fail. To obtain WINNT security information, the NTA$LOGON Utility must be run.

For an RPC server application to impersonate the requesting client, you must complete the following:

1. The first input parameter to each RPC server manager routine is a binding handle which represents the requesting client. If the RPC server application wants to impersonate the client represented by the binding handle, then the RPC server manager routine must call rpc_impersonate_client() with the binding handle as input. This allows the RPC server to use the WINNT and OpenVMS security information of the client instead of the WINNT and OpenVMS security information of the server.
   When the RPC server application wants to run with its original WINNT and OpenVMS security information, it must call either rpc_revert_to_self() or rpc_revert_to_self_ex().
   Running with WINNT security information means that the RPC application accesses a resource on the system that has WINNT access control lists. The operting system checks the RPC application's WINNT security information to determine if access is allowed. If the application accesses a resource with OpenVMS ACLs, it is checked against the OpenVMS security information of the application.

For an RPC client application to send requests that will use WINNT authentication, you must complete the following:

1. The client application must call rpc_binding_set_auth_info() to set WINNT authentication information on the binding.
2. The client application must pass security credential information to rpc_binding_set_auth_info(). Use the rpc_binding_set_auth_info() auth_ident parameter value to pass WINNT security information. The auth_ident parameter can have one of the following two values:
   • The auth_ident parameter supplied to rpc_binding_set_auth_info() is NULL. If this is the case, then the client application will use all WINNT security information from the current address space. If the process that deploys the client RPC application has not acquired WINNT security information for it's address space, then the RPC client's call to rpc_binding_set_auth_info() will fail. To obtain WINNT security information, the NTA$LOGON Utility must be run.
   • Supply a valid rpc_auth_identity_handle_t obtained from a call to rpc_winnt_set_auth_idenity(). This option allows the client to use WINNT security information other than that of the current address space.

The following routines have been created or enhanced to support the WINNT authentication service.

rpc_binding_set_auth_info() rpc_server_register_auth_info() rpc_binding_inq_auth_info() rpc_binding_inq_auth_client() rpc_mgmt_inq_dflt_authn_level() rpc_mgmt_inq_server_princ_name() rpc_winnt_set_auth_identity() rpc_winnt_free_auth_identity() rpc_impersonate_client() rpc_revert_to_self() rpc_revert_to_self_ex()

For more information on the RPC security APIs, see the Digital DCE for OpenVMS VAX and OpenVMS AXP Reference Guide.

5.3 Using the NTA$LOGON Utility

The NTA$LOGON Utility allows client and server applications to obtain WINNT security information. This section provides NTLOGON syntax and usage examples. For more information on the NTA$LOGON utility, see the OpenVMS Connectivity Guide.

NAME

• NTLOGON --- Invokes the NTA$LOGON utility

SYNOPSIS

• ntlogon username password
  Note that all character strings will be converted to upper-case unless they are enclosed in double quotations ("""").

QUALIFIERS

• /LOG
  Displays the result of a transaction.
• /LIST
  Lists the NT credentials for the current process. This is the natural persona.
• /DELETE
  Deletes the NT credentials for the current process.
• /DOMAIN = domain
  Specifies a different domain.

EXAMPLES

The following example shows how to use the NTA$LOGON utility.

$ ntlogon/list [Persona #1 NT extension: Account= "TESTACCNT" Domain= "OPENVMS_ARPC" ] $ ntlogon/delete $ ntlogon/list ERROR: NtOpenProcessToken() failure: -1073741700 0xc000007c %SYSTEM-E-NOSUCHEXT, no such extension found $ ntlogon TESTSACCNT examplepassword $ ntlogon/list [Persona #1 NT extension: Account= "TESTACCNT" Domain= "OPENVMS_ARPC" ] $ ntlogon/log/domain=openvms_dcom "okelley" "password" [Deleting existing NT extension] [Persona #1 NT extension: Account= "okelley" Domain= "OPENVMS_DCOM" ]

For more information on setting up your OpenVMS environment to use WINNT authentication, see the OpenVMS Connectivity Developer's Guide.

This chapter provides the names and locations of important DCE directories and files as they are installed and used with Digital DCE for OpenVMS VAX and OpenVMS Alpha systems. Tables show the correlation between Digital DCE directories and files and their counterparts on other DCE kits.

6.1 DCE Directories

DCE installation and configuration creates a number of directories that are required for proper DCE execution. On Digital DCE for OpenVMS VAX and OpenVMS Alpha, you can access the top-level DCE directory by using the logical name DCE$LOCAL. This is the top-level DCE directory named DCE$LOCAL:[000000]. On an OSF/1 system, the corresponding DCE local directory is created in /opt/dcelocal. The DCE services database, named dce_services.db, and the DCE configuration database, named dce_cf.db, reside in this top-level DCE local directory.

On Digital DCE for OpenVMS VAX and OpenVMS Alpha systems, the DCE endpoint map databases, rpcdep.dat and rpcdllb.dat, which are created when the RPC daemon rpcd starts, are located in the directory DCE$LOCAL:[VAR.RPC]. On an OSF/1 system, these databases are located in the directory /opt/dcelocal/var/rpc.

Table 6-1 lists the names of the DCE directories on Digital DCE for OpenVMS VAX and OpenVMS Alpha and the corresponding directory names on Digital DCE for DEC OSF/1 Alpha systems.

Table 6-1 DCE Directories for OpenVMS and OSF/1

OpenVMS DCE Directory Name	OSF/1 Equivalent
DCE$LOCAL:[000000]	/opt/dcelocal
DCE$LOCAL:[VAR]	/opt/dcelocal/var
DCE$LOCAL:[VAR.DIRECTORY]	/opt/dcelocal/var/directory
DCE$LOCAL:[VAR.RPC]	/opt/dcelocal/var/rpc
DCE$LOCAL:[VAR.RPC.ADM]	None

6.2 Setup Utilities

DCE installation also provides procedures and utilities to help you configure your DCE environment. On Digital DCE for OpenVMS VAX and OpenVMS Alpha, these procedures are placed in the SYS$MANAGER and SYS$STARTUP directories, with the exception of the DCE$DEFINE_OPTIONAL_COMMANDS.COM procedure, which is in the SYS$COMMON:[DCE$LIBRARY] directory. On an OSF/1 system, equivalent utilities reside in /usr/sbin.

Table 6-2 lists the names of the Digital DCE for OpenVMS setup command procedures and their equivalent OSF/1 utilities.

Table 6-2 DCE Setup Utilities for OpenVMS and OSF/1

OpenVMS Filename	OSF/1 Equivalent
DCE$DEFINE_OPTIONAL_COMMANDS.COM	NONE
DCE$DEFINE_REQUIRED_COMMANDS.COM	NONE
DCE$SETUP.COM	dcesetup
DCE$SHUTDOWN.COM	NONE
DCE$STARTUP.COM	NONE

6.3 Executable Images

Following installation on an OpenVMS VAX or OpenVMS Alpha system, all DCE executable images reside in the SYS$SYSTEM directory. On an OSF/1 system, these images reside in /usr/bin.

Table 6-3 lists the names of the executable images on an OpenVMS system and the names of the equivalent images on an OSF/1 system.

Table 6-3 Executable Images for OpenVMS and OSF/1

OpenVMS Filename	OSF/1 Equivalent
DCE$CDSD.EXE	cdsd
DCE$CHECK.EXE	dcecheck
DCE$DTSCP.EXE	dtscp
DCE$GDAD.EXE	gdad
DCE$IDL.EXE	idl
DCE$NIDL_TO_IDL.EXE	nidl_to_idl
DCE$NSID.EXE	nsid
DCE$RPCCP.EXE	rpccp
DCE$RPCD.EXE	rpcd
DCE$RPCLM.EXE	rpclm
DCE$SX.EXE	dcesx
DCE$UUIDGEN.EXE	uuidgen
DCE$ACL_EDIT.EXE	acl_edit
DCE$CADUMP.EXE	cadump
DCE$CDSADV.EXE	cdsadv
DCE$CDSBROWSER.EXE	cdsbrowser
DCE$CDSCLERK.EXE	cdsclerk
DCE$CDSCP.EXE	cdscp
DCE$ADD_ID.EXE	NONE
DCE$DCE_LOGIN.EXE
DCE$DTSD.EXE	dtsd
DCE$KDESTROY.EXE	kdestroy
DCE$KINIT.EXE	kinit
DCEKLIST$.EXE	klist
DCE$NSEDIT.EXE	NONE
DCE$RGY_EDIT.EXE	rgy_edit
DCE$SEC_CLIENTD.EXE	sec_clientd
DCE$SEC_SETUP.EXE	NONE
DCE$X500_ADDCELL.EXE	x500_addcell
DCE$CHPASS.EXE	NONE
DCE$GETCELLS.EXE	getcells
DCE$SEC_ADMIN.EXE	sec_admin
DCE$SEC_CREATE_DB.EXE	sec_create_db
DCE$UAF.EXE	NONE
DCE$LGI_CALLOUTS.EXE	NONE

6.4 Library Images

Following installation on an OpenVMS VAX or OpenVMS Alpha system, all DCE library images reside in the SYS$LIBRARY directory. On an OSF/1 system, these images reside in /usr/lib.

Table 6-4 lists the names of the library images on OpenVMS VAX and OpenVMS Alpha systems and the names of equivalent library images on an OSF/1 system.

Table 6-4 DCE Library Images for OpenVMS and OSF/1

OpenVMS Filename	OSF/1 Equivalent
DCE$KERNEL.EXE	NONE
DCE$LIB_SHR.EXE	libdce.a
DCE$SOCKSHR_IP.EXE	NONE
DCE$SOCKSHR_DNET_IV.EXE	NONE
DTSS$SHR.EXE	NONE
DTSS$RUNDOWN.EXE	NONE
DXD$CDS_SHR.EXE	NONE
DCE$NSEDIT_SHR.EXE	NONE
DCE$SOCKSHR_DNET_OSI.EXE	NONE
DCE$SOCKSHR_TPS.EXE	NONE
DCE$UAF_SHR.EXE	NONE
DCE$UTIL_SHR.EXE	NONE

6.5 Message Files

After you install Digital DCE for OpenVMS VAX or OpenVMS Alpha, all DCE message files reside in the SYS$MESSAGE directory. On an OSF/1 system, the message files reside in /usr/lib/nls/msg/en_US.88591.

Table 6-5 lists the names of the message files on an OpenVMS system and the names of equivalent files on an OSF/1 system.

Table 6-5 Message Files for OpenVMS and OSF/1

OpenVMS Filename	OSF/1 Equivalent
DCE$IDL_MSG.EXE	idl.cat
DCE$RPC_MSG.EXE	dcerpc.cat
DCE$UUIDGEN_MSG.EXE	uuidgen.cat
DCE$CDS_MSG.EXE	dcecds.cat
DCE$SEC_MSG.EXE	dcesec.cat
DCE$IL_MSG.EXE	NONE

6.6 Development Files

On an OpenVMS system, all DCE.h and .idl application development files reside in the SYS$COMMON:[DCE$LIBRARY] directory. You can also access this directory through the logical name DCE. On an OSF/1 system, these files reside in the directory /usr/include/dce. Except for case-sensitivity differences between systems, all .h and .idl files have the same names on both OpenVMS and OSF/1.

6.7 Sample Applications

Both Digital DCE for OpenVMS VAX and OpenVMS Alpha and Digital DCE for DEC OSF/1 Alpha provide RPC and DCE sample applications. On OpenVMS, all example source and build files are located in the following separate subdirectories:

• SYS$COMMON:[SYSHLP.EXAMPLES.DCE]
• SYS$COMMON:[SYSHLP.EXAMPLES.DCE.RPC].
• SYS$COMMON:[SYSHLP.EXAMPLES.DCE.GDE_DCE_APPS]

On OSF/1 systems, the sample applications reside in subdirectories of /usr/examples/dce and /usr/examples/dce/rpc.

On both OpenVMS and OSF/1 systems, example application files reside in subdirectories named for the sample applications. For example, on OpenVMS systems, all Distributed Calendar Program (book) example source and build files are located in the directory SYS$COMMON:[SYSHLP.EXAMPLES.DCE.RPC.BOOK].

On OSF/1 systems, the equivalent files for the calendar program reside in the directory /usr/examples/dce/rpc/book.