Last updated 12/10/2001 10:37 This is preliminary documentation for the kx509 and kpkcs11 modules. It is a summary of the local documentation for the Umich team. Change summary: ------------------------------------------------------------------------- 12/10/2001 - Code for the KCT and mod_KCT has been added. With mod_KCT added to the Apache web server and KCT running on the Kerberos KDC machine, the web server is able to obtain Kerberos service tickets on behalf of the user in order to perform tasks requiring Kerberos authentication for that user. - Minor changes to the kx509 configuration script to find 'make' properly. - KCA logging is changed to use the date in the log. It can be re-opened by sending the process a SIGHUP to keep daily logs in separate files. 08/27/2001 - The windows client is now coded to use a subset of kerberos routines. It will use any kerberos client installation that supports that subset of routines. We have tested against the kclient interface, MIT, KfW 2.1, and kerb95. The use of kerb95 is no longer required for the windows client. (And is discouraged in favor of MIT KfW 2.1). - The unix clients now use K5 by default. - The server (KCA) still supports both K4 and K5 clients. - The way that client determines where to find the KCA has been changed. The client now does a DNS lookup for _kca._udp. to locate the KCA server(s). - The server (KCA) code has been cleaned up so that UMICH-specific database lookups are not used by default while creating the certificate. This should make it easier for other organizations to use the KCA. - The use of RSAref is no longer required and has been eliminated from our build. - We now use the default build of openssl-0.9.6 - We now use MIT kerberos 1.2.1 - We now include a script to create the initial self-signed certificate for the KCA. It is located in the src/server directory. See below for more details. 06/26/2000 This is the first release to add K5 authentication support. The server may be configured to allow K4, or both K4 and K5 authentication. The clients must be configured/built to use either K4 or K5. It is probably desirable to disallow K4 authentication, but that is currently still our default method... ################################################################################ Components ################################################################################ Module Release Where to get it ------ ------- --------------------- openssl 0.9.6 www.openssl.org/source/openssl-0.9.6.tar.gz mod_ssl 2.4.2 www.modssl.org/source/mod_ssl-2.4.2-1.3.9.tar.gz apache 1.3.9 www.apache.org/dist/apache_1.3.9.tar.gz krb5 1.2.1 web.mit.edu/kerberos/www (The latest release *should* work) kx509 In this distribution kpkcs11 In this distribution ################################################################################ Build Order ################################################################################ For clients: 1) krb5 2) openssl 3) kx509 4) kpkcs11 For server (CA): 1) krb5 2) openssl 3) mod_ssl 4) apache 5) kx509 (kca) ################################################################################ Configuration and Build Tips ################################################################################ -------------------------------------------------------------------------------- openssl: -------------------------------------------------------------------------------- Solaris: # Configure for solaris build ./Configure \ --rsarefdir=/afs/umich.edu/group/itd/x509/build/rsaref/local \ -L`pwd` -lRSAglue \ rsaref no-asm --cryptolib=sslcrypto solaris-sparcv9-cc # build solaris version make # build the solaris shared libraries (needed by kpkcs11) cd shlib ./solaris.sh Linux: # Configure for linux build ./Configure \ --rsarefdir=/afs/umich.edu/group/itd/x509/build/rsaref/local \ -L`pwd` -lRSAglue \ rsaref no-asm --cryptolib=sslcrypto linux-elf # build linux version make # build the linux shared libraries (needed by kpkcs11) cd shlib ./linux.sh Win32: # Note that the Win32 configure requires Perl 5!, # and Microsoft VC++ 4.0 or later perl Configure VC-WIN32 ms\do_ms nmake -f ms\ntdll.mak # Note that windows builds an inherently sharable DLL AIX: # Configure for an AIX build # (Note we used gcc because of license snags with the # IBM compiler.) ./Configure \ --rsarefdir=/afs/umich.edu/group/itd/x509/build/rsaref/local \ -L`pwd` -lRSAglue \ rsaref no-asm --cryptolib=sslcrypto aix-gcc # build aix version make # Note that AIX .a libraries are sharable -------------------------------------------------------------------------------- mod_ssl: -------------------------------------------------------------------------------- NOTE -- 1) This assumes that the apache code is in a directory next to this one 2) "zingara" below is the name of one of our CAs. This key/cert conbination were created using openssl utilities. Solaris: ./configure \ --with-apache=../apache \ --with-ssl=/afs/umich.edu/group/itd/x509/build/openssl \ --with-rsa=/afs/umich.edu/group/itd/x509/build/rsaref \ --with-crt=/var/https-1.3.9/test/conf/ssl.crt/zingara.crt \ --with-key=/var/https-1.3.9/test/conf/ssl.key/zingara.key -------------------------------------------------------------------------------- apache: -------------------------------------------------------------------------------- Solaris: CC="/opt/SUNWspro/bin/cc" \ EXTRA_CFLAGS="-g" \ LIBS="-ldes -lresolv" \ KRB_BASE="/afs/umich.edu/group/itd/x509/dist/sun4x_56/krb5" \ SSL_BASE="/afs/umich.edu/group/itd/x509/build/openssl" \ RSA_BASE="/afs/umich.edu/group/itd/x509/build/rsaref" \ ./configure \ "--with-layout=Apache" \ "--enable-module=krb" \ "--enable-module=ssl" LD_LIBRARY_PATH=/afs/umich.edu/group/itd/x509/dist/sun4x_56/krb5/lib \ make -------------------------------------------------------------------------------- krb5: -------------------------------------------------------------------------------- Note -- The most important part of the configure parameters is to make sure you wind up using the Solaris compiler on Solaris, and enabling shared libraries. It was important for us to enable K4 and AFS support! Solaris: mkdir sun4x_56 cd sun4x_56 ../configure --with-cc=/opt/SUNWspro/bin/cc \ --prefix=/krb5 \ --with-krb4 \ --with-afs=/usr/itd/packages/a/afs-3.4ap/transarc/sun4x_56.new \ --enable-shared -------------------------------------------------------------------------------- kx509: -------------------------------------------------------------------------------- Note -- configure is now a part of the distribution. There are options to configure to specify/override the default path locations that are included for the UMICH environment. Solaris: # For client support ./sun4x_56_rebuild # For server support ./sun4x_56_server Linux: ./i386_linux22_rebuild Aix: ./rs_aix43_rebuild Win32: From a dos shell prompt enter: .\kx509.bat This will create an i386_nt35\kx509 directory, use the src/kx509.dsp.org file as a template and create a VC++ project file in the directory created above At this point, you should be able to open up the project from the VC++ GUI environment. We are using VC++ 6.0, you may have problems with other versions. -------------------------------------------------------------------------------- kpkcs11: -------------------------------------------------------------------------------- Solaris: ./sun4x_56_rebuild Linux: ./i386_linux22_rebuild Aix: # Not yet supported Win32: From a dos shell prompt enter: .\kpkcs11.bat This will create an i386_nt35\kpkcs11 directory, use the src/kpkcs11.dsp.org file as a template and create a VC++ project file in the directory created above At this point, you should be able to open up the project from the VC++ GUI environment. We are using VC++ 6.0, you may have problems with other versions. ################################################################################ After kx509/kca is built: ################################################################################ Set up the KCA Create the proper srvtab or keytab for your Kerberos environment. The kca program accepts a configuration file by specifying the -c option. This configuration file can override the local UMICH defaults. There is a script in the src/server directory called mkcacert.sh. Along with this script is mkcacert.README which explains what might need to be changed in the script before running it. There are several options that can be changed via the kca config file (default location is /var/kca/kca.cnf). See the sample configuration file below. XXX Set up some protected web pages XXX Running the kx509 client Run the correct program on the given platform to obtain a kerberos TGT. For our K4 environment, on Solaris, Aix, and Linux this is the kinit program or the klog program in our AFS environment. For Kerb95, this is having the "tman" program active. Run kx509. This should generate a private/public key pair, obtain a kerberos service ticket to talk to the kca, send kerberos authenticator and public key to be signed, receive the signed certificate, and store it. For Unix platforms, the private key and certificate are stored in the kerberos credentials storage. For Win32, the private key and cert are stored in the correct area within the registry. At this point, Internet Explorer should be able to find and use this certificate for secured web pages. ################################################################################ After kpkcs11 is built: ################################################################################ The Unix platforms have a test program test/t that should be built. Run this program to verify that all the shared library magic is set up correctly. This is much easier to debug at this point, rather trying to figure out why netscape will not use your shared library! If the test program is able to find and load all the shared libraries successfully, then it should print the following message: C_Initialize returned 0 At this point, you can add the PKCS11 module to Netscape. Select the "Security" button at the top of the browser. (This is also available from the "Communicator => Security Info" menu option.) On this menu, select "Cryptographic Modules" from the left side. There should be the standard "Netscape Internal PKCS #11 Module" shown. Click the "Add" button to add another PKCS #11 module. In the next dialog, "Security Module Name" is any name you want to give to your PKCS #11 module. "Security Module File" should be the complete path name to the kpkcs11 module previously built. On windows this will be a kpkcs11.dll file, on Linux or Solaris it will be called kpkcs11.so. On AIX, I suspect it will be called kpkcs11.a. After filling in the path and selecting "OK", there should now be another Cryptographic Module listed with the name that you gave. If it does not appear, Netscape had trouble finding, loading, or running your pkcs11 module. Note that all the shared libraries required by the pkcs11 module must also be found! If the new cryptographic module shows up, then you should now be able to select the "Certificate : Yours" link in the left side of the security dialog to see your certificates. This should show the certificate obtained by the kx509 program. You should now be able to go to a secured web page and use your certificate to access it's data. ################################################################################ Sample kca.cnf file: ################################################################################ # # KCA Configuration file (my test version -- kwc) # [ ca ] default_ca = CA_default # The default ca section [ CA_default ] serial = /var/kca/serial certificate = /var/kca/conf/buzzkca.crt private_key = /var/kca/conf/buzzkca.key email_domain = OUTPOST.CITI.UMICH.EDU [ kx509 ] keytab = /var/kca/buzz_kca_keytab