added documentation

INSTALL

@@ -4,11 +4,11 @@ Installation
 IdPC uses automake and autoconf which should make compilation and installation
 a breeze.  Kind of.
 
-Basic usage is
+Basic usage is::
 
-  ./configure
-  make
-  make install
+ ./configure
+ make
+ make install
 
 It will most likely bail out because of missing libraries.  You need libxml2
 (configuration file support), neon (HTTP client support) and lasso (Liberty
@@ -84,3 +84,8 @@ PostgreSQL
 
 .. include:: create-db.sql
 
+MySQL
+-----
+
+Support not yet implemented.
+

Makefile.am

@@ -1,4 +1,4 @@
-SUBDIRS = src data
+SUBDIRS = src data doc
 
 EXTRA_DIST = CodingStyle
 

configure.ac

@@ -66,6 +66,7 @@ fi
 AC_OUTPUT([
 Makefile
 data/Makefile
+doc/Makefile
 src/Makefile
 ])
 

doc/.cvsignore

@@ -0,0 +1,4 @@
+Makefile
+Makefile.in
+manual.html
+

doc/Makefile.am

@@ -0,0 +1,9 @@
+docdir = $(prefix)/share/doc/idpc
+
+doc_DATA = manual.html default.css
+
+manual.html: manual.txt
+	rest2html manual.txt > manual.html
+
+EXTRA_DIST = manual.txt default.css
+

doc/default.css

@@ -0,0 +1,49 @@
+body {
+	font-family: sans-serif;
+}
+
+h1 a, h2 a, h3 a, h4 a {
+	text-decoration: inherit;
+	color: inherit;
+}
+
+pre.literal-block {
+	background: #eee;
+}
+
+h1.title {
+	text-align: center;
+	border-bottom: 1px solid black;
+}
+
+
+div.document {
+	margin-top: 1em;
+	border-top: 1px solid black;
+}
+
+div#table-of-contents {
+	float: right;
+	border: 1px solid black;
+	margin: 1em;
+	width: 17em;
+	background: #eee;
+}
+
+div#table-of-contents ul {
+	padding-left: 1em;
+	list-style: none;
+}
+
+div#table-of-contents p {
+	background: #ddd;
+	text-align: center;
+	border-bottom: 1px solid black;
+	margin: 0;
+}
+
+th.docinfo-name {
+	text-align: right;
+	padding-right: 0.5em;
+}
+

doc/manual.txt

@@ -0,0 +1,129 @@
+===========
+IdPC Manual
+===========
+
+:Author: Frederic Peters
+:Contact: fpeters@entrouvert.com
+:date: $Date$
+:revision: $Revision$
+:copyright: Copyright © 2004 Entr'ouvert
+
+.. contents:: Table of Contents
+.. section-numbering::
+
+Introduction
+============
+
+IdPC is an implementation of a Liberty Alliance Identity Provider in the form
+of several CGI C programs.
+
+It supports the following IDFF-1.2 core profiles:
+
+ - SSO (Artifact and POST)
+ - Single logout
+
+It will implement other core profiles in the future.
+
+IdPC can authenticate users through several means including HTTP authentication
+and client certificates.
+
+
+.. _INSTALL:
+.. include:: ../INSTALL
+
+
+IdPC Configuration
+==================
+
+IdPC needs a configuration file to work; its location depends of compilation
+options; IdPC will tell you the correct path if you call one of the CGI with
+the ``--help`` argument::
+
+  $ /usr/lib/cgi-bin/idpc/soapEndpoint --help
+ This is IdPC; it is meant to be used as a CGI
+ 
+ Config file should be installed as:
+   /etc/idpc/config.xml
+
+The configuration file must be a valid XML file and its root element should be
+named "idpc" and placed in the following namespace
+``http://www.entrouvert.org/namespaces/idpc``.
+
+metadataFilePath:
+	path to the Liberty Alliance IdP metadata file
+
+idpPublicKey:
+	path to the IdP public key (PEM encoded)
+
+idpPrivateKey:
+	path to the IdP private key (PEM encoded)
+
+idpCertificate:
+	path to the IdP certificate (PEM encoded) (?)
+
+serviceProvider:
+	element that should contains three other elements; metadataFilePath,
+	spPublicKey and spCaCertificate.  You can have several
+	<serviceProvider> elements (XXX not supported yet)
+
+authenticationMethod:
+	authentication method to use, detailed below
+
+dbhost:
+	hostname where the IdPC database is installed (optional)
+
+dbport:
+	port where the IdPC database is listening (optional)
+
+dbname:
+	name of the IdPC database
+
+dblogin:
+	login to connect to the IdPC database
+
+dbpassword:
+	password to connect to the IdPC database
+
+ocspUrl:
+	URL to the OCSP service for certificate validation (optional)
+
+ocspIssuer:
+	path to the OCSP issuer certificate (PEM encoded)
+
+
+Authentication Methods
+----------------------
+
+HTTP authentication
+```````````````````
+
+Keyword: ``http``
+
+HTTP authentication is handled by the web server; it should pass a REMOTE_USER
+environment variable to the CGI.  Apache allows many sources for HTTP
+authentication including LDAP directory and PostgreSQL and MySQL databases.
+
+The REMOTE_USER will be used as key to identify users in the database.
+
+Certificate authentication
+``````````````````````````
+
+Keyword: ``certificate``
+
+This authentication relies on Apache ``mod_ssl`` to set several environment
+variables; your Apache configuration must contains a ``SSLVerifyClient``
+option with ``optional`` or ``require`` as value.
+
+The certificate serial will be used as key to identify users in the database.
+(XXX: this will change)
+
+Additionally if you have set OCSP options in the configuration file, a OCSP
+connection will be made to check certificate validity.
+
+
+Copyright and License
+=====================
+
+IdPC (both code and documentation) is copyright © 2004 Entr'ouvert and released
+under the GNU General Public License.
+

src/idpc.h

@@ -38,6 +38,7 @@
 
 int error_page(char *msg);
 char* get_config_string(char *xpath);
+void handle_args(int argc, char *argv[]);
 
 int db_init();
 int db_get_dumps(char *user_id, char **user_dump, char **session_dump);

src/single_sign_on.c

@@ -402,6 +402,11 @@ int main(int argc, char *argv[])
 {
 	int rc;
 
+	if (argc > 1) {
+		handle_args(argc, argv);
+		return 0;
+	}
+		
 	rc = init_config();
 	if (rc != 0) {
 		return error_page("Failed to init configuration");

src/soap_end_point.c

@@ -253,6 +253,11 @@ int main(int argc, char *argv[])
 {
 	int rc;
 
+	if (argc > 1) {
+		handle_args(argc, argv);
+		return 0;
+	}
+		
 	rc = init_config();
 	if (rc) {
 		return error_page("Failed to init configuration");

src/utils.c

@@ -29,3 +29,17 @@ int error_page(char *msg)
 	return 0;
 }
 
+void handle_args(int argc, char *argv[])
+{
+	int i;
+
+	for (i=1; i<argc; i++) {
+		if (strcmp(argv[i], "--help") == 0) {
+			printf( "This is IdPC; it is meant to be used as a CGI"
+				"\n\n"
+				"Config file should be installed as:\n"
+				"  %s\n", SYSCONFDIR "config.xml");
+		}
+	}
+}
+