PHP Cosign Filter Installation

Validation Service

If you want to use V3 protocol, setup validation service first:

Copy the php source "valid" to you Web server root directory ROOT subdirectory cosign:
```
	mkdir ROOT/cosign
	cp valid ROOT/cosign
```
If you are running Apache, copy also .htaccess file to this directory (or setup your server to execute "valid" as PHP script):
```
   	cp .htaccess ROOT/cosign
```

Setup appropriate access rights so the file is readable to Web server:

	chgrp www ROOT/cosign 
	chgrp www ROOT/cosign/valid
	chgrp www ROOT/cosign/.htaccess
	chmod 750 ROOT/cosign
	chmod 640 ROOT/cosign/valid
	chmod 640 ROOT/cosign/.htaccess

Modify CosignValidationErrorRedirect and CosignValidReference to match your setup (see cosign-3.1.1/README) in ROOT/cosign/valid:
```
   	vi ROOT/cosign/valid
```

Filter Setup

Copy PHP scripts cosign.php and cosign_config.php to your PHP include directory (you have to setup it in php.ini!):
```
  	cp cosign.php cosign_config.php /usr/local/include/php
```
Edit configuration file and setup all config options:
```
	vi /usr/local/include/php/cosign_config.php
```
1. Certificate file - copy Cosign client certificate and private key in PEM format to one file (CosignCryptoLocalCert)
2. CA certificate to verify Cosign server certificate (CosignCryptoCAFile)
3. Cosign server hostname (CosignHostname) and URL (CosignRedirect)
4. Cosign service (CosignService)
5. Cookie files directory location (CosignFilterDB - must be writable by your Web server!)
6. Filter log file (CosignFilterLog)
7. Setup Cosign protocol version (CosignProtocolVersion). Version 2 filter can communicate with version 3 cosignd server (if allowed in cosign.conf).
8. Leave debug output initially on (CosignFilterDebug)

Configuration options are merged from the global configuration file (cosign_config.php), local configuration file (.cosign.php in Web page directory) and the first argument in cosign_auth() call. All configuration options have the same meaning as in the original Apache filter module. Only boolean options have different values false (off) and true (on).

Usage

Each page that is protected by Cosign must call cosign_auth() function at the beginning:

<?php
// Some Web page in PHP
	require_once("cosign.php");
	if (cosign_auth()) {	// Authentication OK
	    echo "Authenticated as ".$_SERVER['REMOTE_USER']."
";
	} else {		// Authentication failure
	    echo "Not authenticated";
	    die();
	}
....
?>

Function cosign_auth(array, boolean):

The first argument is configuration options array. Your script can localy change any configuration option from cosign_config.php. The second argument can suppress internal ob_start() in cosign_auth(), if your script is doing it:

<?php
// Some Web page with ob_start()
	ob_start();
	require_once("cosign.php");
	...
	if (cosign_auth(array(), false)) { 	...
	...
?>

After setup verification and testing, change CosignFilterDebug to false to suppress debug logging.

SECURITY NOTICE

Filter Certificate file has to be readable by Web server executing PHP scripts. That means, any user PHP script on this Web server can read this Certificate file (and its private key). Don't use Web server certificate as Cosign Filter Certificate! If Cosign Filter Certificate is used only for cosign client verification, its disclosure should be probably harmless.