1. INTRODUCTION This readme.1 file describes how to begin to understand how the example programs are built and run. This directory tree represents the complete build environment for the Kerberos example applications. The build environment is based on the GMAKE tool for VMS from the GNU project. 2. HOW TO BUILD You will find the GMAKE executables in this top level directory and you will first need to execute: $ @GMAKE_SETUP.COM to be able to initiate a build using this tool. Once you have done this, you can build either the VAX or the Alpha versions of the example programs. 2.1 Building VAX To build the VAX version, you need to be logged into a VAX system and set default to this directory. The command is simple: $ gmake "VAX=1" Note that 'VAX' must be in uppercase for the gmake tool to recognize the uppercase VAX macro definition in Makefile.vms, and you MUST be sure that KRB$ROOT is defined. If KRB$ROOT is not defined, you will not be able to find the required kerberos include files. All of the example programs will be compiled and linked against the Kerberos libraries on the local VAX system. The VAX images produced will be placed in a [.VAX] subdirectory in each example component. Note that you can use the gmake command in any subdirectory of the build tree where a Makefile.vms file exists and the correct builds will be done. 2.2 Building Alpha Building the Alpha images is an easier command, but you still need to check that KRB$ROOT is defined as above. The command to build the Alpha examples is: $ gmake The Alpha images will be built as 64 and 32 bit images where possible and the MIT examples are all built with short pointer support to match the Socket interfaces used in these examples. The respective 32 and 64 bit images will be placed in the respective 32 and 64 bit directories for each component that can be built two ways. If there is no 32 or 64 bit directory under the component being built, the images are all 32 bit and use the 32 bit krb$rtl32.exe sharable image. Note that you can use the gmake command in any subdirectory of the build tree where a Makefile.vms file exists and the correct builds will be done. 2.3 Building Itanium To build the Itanium version, you need to be logged into an Itanium system and set default to this directory. The command is simple: $ gmake -f MAKEFILE.VMS "IA64=1" The Itanium images will be built as 64 and 32 bit images where possible and the MIT examples are all built with short pointer support to match the Socket interfaces used in these examples. The respective 32 and 64 bit images will be placed in the respective 32 and 64 bit directories for each component that can be built two ways. If there is no 32 or 64 bit directory under the component being built, the images are all 32 bit and use the 32 bit krb$rtl32.exe sharable image. Note that you can use the gmake command in any subdirectory of the build tree where a Makefile.vms file exists and the correct builds will be done. 2.4 Build Macros The gmake command will take any quoted string on the command line as an environment variable for use inside the MAKEFILE.VMS build description file. "VAX=1" is one such macro that can control which type of build is performed. The other helpful macro is the "DEBUG=1" macro that will produce source listings and debug object files and images. If you are interested, you are free to add macros to the makefile.vms description files or change the settings in the various MAKEFILE.VMS files to customize your builds. The MAKEFILEs provided are abstracted to a small degree. We thought it more useful for you to be able to see how things are done explicitly so that you could do your own abstractions on these gmake builds or others for which you may find gmake useful. Note that you can override any macro in the makefile on the gmake command line, but you should not need to do this. 2.5 Build Errors you may see 1. The Gss sample link will complain about a multiply defined variable in the decc$rtl. This is only seen with the DECC 5.7 compiler, and appears to be harmless. 2. If you get compiler errors about /pointer support you probably are building on VAX without having used the uppercase "VAX=1" macro on the gmake command line. 3. A 'gmake clean' command will clean everything in the VAX and alpha directories that exist below the current directory from which you may issue the command. From the top level directory, all generated files will be removed for vax and Alpha all the way down the tree. To limit this behavior, simply set default to a lower level directory. The lowest level directories will require two 'gmake clean' commands to remove the VAX and the Alpha images. The VAX clean requires the "VAX=1" macro to be used with the gmake command. 2.6 Build notes for the VMS examples in [.vms] This [.vms] directory tree contains the KRB and GSS example programs for VMS. These are the same programs that have been shipping with the kit since V1.0. Typing gmake in the vms directory will produce executable images in the [.krb] and [.gss] directory trees. Three sets of images can be created for each. One set is for the 64 bit images, another is for the 32 bit images, and the last is for VAX. The 64 bit images are compiled with LONG pointer support and link with the KRB$RTL.EXE sharable image. You must be on an Alpha or Itanium system. The 32 bit images are compiled with SHORT pointer support and link with the KRB$RTL32.EXE sharable image. DECC defaults to short pointer support if none is specified. You also must be on an Alpha or Itanium system. The VAX images are built when typing gmake on a VAX system and all VAX images are built with 32 pointers (that is all there is on VAX). The images are placed in the respective [.VAX] subdirectories of each component tool. 3. Running the MIT example programs Set default to [.MIT] where you will see the directories holding the MIT example programs. You will first be required to configure the example principals in the KDC. You only need to do this one time for each node that will run as a client. This can be done by running: $ kinit "to your admin principal name" $ @SETUP_PRINCIPAL KDC nodename If necessary, you can clean and restart the principal name registration by typing: $ @SETUP_PRINCIPAL KDC CLEAN nodename Then you can go back and setup the principal fresh. You may also have to kinit in both windows to freshen the credentials with the latest principal credentials. 3.1 Running The gss-sample example. You will need two windows. In both, set default to [mit.gss-sample] and run: $ @setup This command file will setup the required symbols and show you an example of how to invoke the server and client images. Run the server command from one window and the client command from the other. 3.1.1 Client Errors 0. unknown host servernode Solution: You used the wrong nodename for the server to which your client will connect, or your server on the remote/local node is not running. Replace 'servernode' with the real nodename of the server being contacted. 1. GSS-API error initializing context: Miscellaneous failure GSS-API error initializing context: Server not found in Kerberos database Solution: You need to configure your KDC with the sample/yournode principal. To do this in the current directory, use: @setup KDC yournode 2. If you get the following error when running the client command: Sending init_sec_context token (size=567)...continue needed... GSS-API error initializing context: Miscellaneous failure GSS-API error initializing context: Decrypt integrity check failed Solution: First, try a KINIT in both windows. This will probably not work. Second, Clean and Re-configure the sample/yournode principal using: @setup KDC CLEAN yournode @setup KDC yournode kinit again in both windows (both windows must use the same credentials. Even though they use the same cache, this does not guarantee that they can authenticate to one another). You should be able to start the server and run the client now. The rest of the MIT example programs should be fine now. 3.2 Running The sample example. Set default to the [mit.sample] directory in both terminal windows and run: $ @setup This command file will setup the required symbols and show you an example of how to invoke the server and client images. Type the server command into one window and the client command into the other. NOTE: Remember to use your real server nodename inplace of the nodename 'opnnow' that is printed out by the setup.com file. 3.3 Running the simple Example. Set default to the [mit.simple] directory and run: $ @setup This command file will setup the required symbols and show you an example of how to invoke the server and client images. Type the server command into one window and the client command into the other. NOTE: Remember to use your real server nodename inplace of the nodename 'opnnow' that is printed out by the setup.com file. 3.4 Running The user_user example. Set default to the [mit.user_user] directory and run: $ @setup in both windows. This command file will setup the required symbols and show you an example of how to invoke the server and client images. You will need to have the service name registered as a TCPIP service name. To do this (and it only needs to be done 1 time) type: $ @set_service Or in one of the two terminal windows, type: $ @setup register 4. Running the VMS Example Programs In two windows set default to [vms] and run $ @setup.com This command file will define the required foreign commands for the KRB abd GSS example programs. It also prints out information about how to run the programs. The principals required are specific to each node that will run the clients. Running the setup_principals.com file is the easiest way to configure the KDC. You will need to provide the nodename on which each client will run and also the administrator password in quotes to preserve the case of the password. Run the command file like this: $ @setup_principals theNode "YourAdminPWD" for each nodename that you expect to run the example clients. ============ Manual instructions for configuring the KDC ============== For the server images, if the port number is not specified, then it will be assumed that the server is being run as a TCP/IP service. If the port number is not specified for a client image, then port number 4444 is assumed. The following Kerberos principals will need to be created: gss_sample/@ krb_sample/@ Here should be your specific Kerberos Realm, but the @realm part of any principal name will be appended by default if it not specified. Also will indicate the node on which this example will be run. Create principals for as many nodes which will be used with the appropriate example. Then, add the created principals to the key table and securely propogate it the desired nodes. To add the services and key table entries execute the following Kerberos Adminstrator commands: $ kadmin Enter password: KADMIN: addprinc -randkey gss_sample/ KADMIN: addprinc -randkey krb_sample/ KADMIN: ktadd gss_sample/ KADMIN: ktadd krb_sample/ KADMIN: exit OR you can run setup_principals.com to do this for you. $ @setup_principals clientnode "adminpassword" for each node that will host an example.