Cosign Frequently Asked Questions
	Building, Installation, and Administration

This guide covers downloading, building, configuring, and installing cosign on your web server. For documentation on the weblogin environment at the University of Michigan, please consult their documentation.

• How do I test that cosign is installed and running?

See the scripts/hello directory in your cosign distribution. This directory includes helloCosign scripts and programs in various programming languages. Install one of these in your web server's document root to verify that the REMOTE_USER environment variable is being properly set and made available to your deployment environment.

• helloCosign.jsp says "Hello, null!" when I run it.

This is happening because Tomcat is not configured to use Apache's authentication.

Make sure that your connector description ( ajp13 or Coyote ) includes the parameter "tomcatAuthentication=false" if you are using Tomcat prior to 4.1.18. Otherwise ( or additionally, your choice ) add the line "request.tomcatAuthentication=false" to your jk2.properties file and restart Tomcat.

• After installing mod_cosign.so, Apache gives the error:
  Cannot load mod_cosign.so into server: (reason unknown)

The httpd that ships with MacOS X 10.2 ( Apache 1.3.26 ) is compiled in such a way that many third party modules give this error on load ( just ask google ). We have not solved the problem yet, but you can work around it by compiling your module on a previous version of MacOS X ( it will then load under Jaguar ) or building your own copy of Apache 1.3.26 from source.


• I'm trying to test a new service. It doesn't work and Apache logs something like:



\x80g\x01\x03 or
\x80g\x01\x03\x01


This is a fairly common mod_ssl error and means that your browser has sent an https request over a non-ssl port. Look for a line like: https://servername:80/ elsewhere in the log. Make sure, if 443 is listening and you were just trying to go to https://servername/ that SSLEngine is On & configured.
 
We've found all browsers behave differently in response to this error. e.g.:
Mozilla: "weblogin.somewhere.edu has sent an incorrect or unexpected message"
Safari: "Could not open the page n.n.n.n because Safari could not establish a secure connection to the server n.n.n.n."
I.E.: displays "pretty" error screen


• I'm having certificate issues, help!

Start by making sure you have your certificate installed correctly, and that it can be used as an SSL client certificate:

openssl verify -CApath path_to_CAdir -purpose sslclient server.crt

This will only work if the root certificate for the CA that signed your client's cert is in your CA directory.


• I'm getting vague and unhelpful SSL errors, but my certificate is verified. What else can I do?

There's an openssl tool called "s_client" that will behave like an SSL client. Try these options to help with further debugging. You can then discuss further errors on the cosign-discuss mailing list. Note that you should run the s_client command as the same user the webserver will be running as - typically "www" or some such. Do not run this command as root, as it makes it more difficult to catch permission problems.

openssl s_client -connect cosign-test.example.edu:6663 -cert /etc/apache/certs/cosign-test.cert -key /etc/apache/certs/cosign-test.key -CApath /var/cosign/certs/CA -showcerts -state -debug -crlf -starttls smtp

• How do I configure Tomcat 4.1.29 to work with mod_cosign?

To enable Tomcat to see the Cosign-authenticated user from Apache, it needs a special configuration. 4.1.29 has a new way to do this, which is really an old way that works again.

you'll want in server.xml: tomcatAuthentication="false"
e.g.:

<!--Define a Coyote/JK2 AJP 1.3 Connector on port 8009-->
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
	port="8009" minProcessors="5" maxProcessors="75"
	enableLookups="true" redirectPort="8443"
	acceptCount="10" debug="0" connectionTimeout="0"
	useURIValidationHack="false" tomcatAuthentication="false"
	protocolHandlerClassName="org.apache.jk.server.JkCoyoteHandler"/>

It no longer needs anything special (or at all) in the jk2.properties file.

• How can I convert my X509 cert/key pair into pkcs12 format?

The following openssl command should do the trick:

    openssl pkcs12 -in example.cert -inkey example.key \
    -export -out excert_key.p12
    

• How do you retrieve the REMOTE_USER value set by the IIS Cosign filter?

The ISAPI extension GetServerVariable() function

The ISAPI filter GetHeader() function

• Where can I find more documentation?
• In the multiple README files and manual pages that ship with the various cosign distribtions.
• In the cosign wiki.
• What is to prevent Friend email messages from being intercepted and used by someone else?

Not a thing. Friend account creation works pretty much the same way, you'll notice. These are email-based accounts, they are as secure as email -- not very. They are designed to enable collaboration with unaffiliated users, on a casual basis, where authorization is typically managed directly by the affiliated user. Don't issue access to sensitive information to "friends," e.g., information protected by HIPAA, FERPA, etc. It is possible to have a UMICH.EDU Kerberos principal issued to people who need more than casual access.

• I get an error like this when I build mod_cosign:



usr/bin/ld: ../../common/fbase64.o: relocation R_X86_64_32S can not be used when making a shared object; recompile with -fPIC

This is probably because you are on a 64bit machine with a very recent version of gcc, and as such, you need to build shared libraries. We'll be rolling a fix into autoconf for this issue in a future release, but for now just do the following.

	    cd libsnet; ./configure --enabled-shared
	    

This will build libsnet as a shared library in addition to the default, which is static.

You also want to add -fPIC to the DEFS line in cosign/common/Makefile.

• I get an error like this when I build cosign:



from snet.c:22: /usr/include/openssl/kssl.h:72:18: krb5.h: No such file or directory
or
configure: error: header file <openssl/ssl.h> is required for this software. You may be running RedHat 9.

You are likely running Redhat 9, or an implementation of ssl that expects kerberos. On Redhat 9, kerberos is in a non-standard place, and so, by default, configure may not find it. Add "env CPPFLAGS=-I/usr/kerberos/include" before you run configure. So in csh your configure line will look like this:

		env CPPFLAGS=-I/usr/kerberos/include ./configure
	    

and in bash or sh you'd type:

		CPPFLAGS=-I/usr/kerberos/include ./configure
	    

The next release of cosign will detect this issue during configuration, but the fix remains the same.

• How does replication work?

The cosign servers share user data through two mechanisms. First, there's a "best effort" replication stream. This causes commands like login, register, and logout, to be repeated to peer cosign servers. Most user data thus exists on all available cosign servers. Second, monster propagates both last-check times and the logged-out state between servers. This makes dropping the logout during replication less of a problem. The logout.cgi also sets the login cookie to "null". This is another source of logout resilience.

Because of the possible delay between checks and the propagation of last-check times, the server will respond with a 5xx response for a few minutes after the user has apparently timed out. Clients interpret 5xx to mean, effectively, "I don't know, ask someone else". If all servers respond with 5xx, the filter will consider the user to be logged out.

The goal for the filter is to spread it's load across all cosign servers. Thus, multiple cosign servers improves both resilience and capacity.

• After I logout I can still access my Cosign Protected service for a small window of time. Is Cosign broken? What's wrong?

Cosign is not broken and you have done nothing wrong. You merely need to customize and make use of the local logout script provided in scripts/logout. The filters have a cache time (default 2 minutes) during which they will not validate a user's status. As such, when a user returns post logout, the cache is still valid and the user is still "logged in" to that one site for a few seconds. To avoid this, simply call the local logout script which will re-direct the user to the main logout script.

• Can I direct a user to a specific location upon logout?

Simply add a redirect URL to the logout script:

	    /cgi-bin/logout?http://www.google.com/
	    

This will override any destination set using --with-cosignlogouturl.

• Using CosignHttpOnly on MacOS X Server redirects me to port 16080 - what's up with that?

That's apparently Performance Caching. Turn off the 'Performance Cache' option in Server Admin for your website.

• I want to use Apache's MPM worker. Is that okay?

Version 3.2.0 and prior are not thread-safe. If you use them with any multi-threaded version of Apache, you'll experience random cookie validation failures (and possibly, but unlikely, user impersonation). Wait for a thread-safe version (development is underway, and is likely to be in the 3.3.0 filter).