Apache Web Server Module to facilitate Citizen Card Authentication in Web Development

Project Details


GPL v2

Purpose of this Project

Help developers integrate Citizen Card (Cartão de Cidadão) authentication more easily on their web sites.

Project Description

Development of a module for the Apache Web Server, in order to facilitate the integration of existing citizen card authentication technologies in web development.

The development will be focused on the following features:

  • Seamless redirection to the authentication web application;
  • Authentication token integration on the target web site.


This section shows the roadmap for the project.

Phase 1:

  • Investigation of the technologies involved;
  • Interception of web authentication requests using an Apache HTTP Server module.

Phase 2:

  • Further investigate the developed authentication applet;
  • Create web session based on authentication results.

Phase 3:

  • Update the wiki with the developments;
  • Write the Final Report (achievements, future work, etc.);
  • Final Presentation (w/demonstration).

Further information regarding project planning can be found in the Project Documentation section.

Risk Mitigation, Monitoring and Management Plan

Risks Identified

  • Apache Module development is rare, and so, there are fewer examples of common bugs and examples;
  • Although there was some experience with Apache HTTP Servers, it was mostly configuration, not development;
  • C programming language usage requires more attention to low-level details that with other languages.

Risk Mitigation

  • When confronted with new bugs, try to participate in discussions with peers and online communities;
  • Read the API reference and bibliography;
  • Pay attention to critical parts of code (memory allocation and manipulation);
  • Develop using good practices and document code.

Risk Monitoring

  • Create daily targets and keep progress on their completeness;
  • Inform mentor of updates, especially unforeseen developments (i.e. "approach X doesn't work, must do Y");


Caixa Mágica Software

Company Description

Caixa Mágica Software is a company specialized in open-source solutions. Having a wide range of products and services developed internally since 2000, it aims to create added value for each client. According to GFK market report, Caixa Mágica is leader in portuguese Linux market in the retail channel.

Caixa Mágica is today present in hundreds of portuguese shops and specialized resellers (FNAC, Vobis, Staples, ...), in Hospitals, Municipal Authorities, and in 1.100 schools spread all over the country, more than 10 universities and thousands of enterprises.

Caixa Mágica is organized in the following units:

  • Software: The software development unit is the core of Caixa Mágica Software. It is responsible by the production of Linux Caixa Mágica in two flavours: Desktop and Server. Each version has a life cycle of one year. This unit is also responsible by minor developments in projects of Professional Services Unit that require parametrization or modification of open-source software. That is the case of CMS (Content Management Systems) and E-Learning projects.
  • Professional Services: This unit is responsible for providing professional support to the client when integrating open-source software at its IT infrastructure. It has 5 different sub-units: IT integration, SMB, Outsourcing, Large projects and Migrations.
  • Training: Since 2002 that Training Unit is very active in providing Linux and System Administration training to IT professionals. This area offers three different solutions: training at Caixa Mágica facilities, "on-site" training at the client facilities and E-Learning modules.
  • Appliances: Caixa Mágica Appliances are turn-key products that integrate both software and hardware and are ready to be used by the client. The access is done through a Web interface and a Setup application without access to command-line. These products include support services.


Vasco Silva

Trainee Details: Carlos Filipe Simões

Past experience

Mainly academic projects for the last 6 years, several small tasks for the NEERCI group, and some hobby Linux time.

Current Situation

Finished the curricular courses for his MSc in Computer Networks Engineering at Instituto Superior Técnico and is currently developing his thesis for a "Guidance System for Visually Impaired Athletes".

Project Documentation

Motivation for the Project

Alot of websites these days use individual user accounts, in order to better cater to their visitors' needs, be it by allowing customizations the layout, providing identity in interactions, access control, and other functionalities.

Using the portuguese Citizen Card for authentication is something that is somewhat appealing to both users and site admnistrators: while the former can have a single safe set of credentials for these sites, the latter gains more assurances regarding the identity of the site's participants. However, using this technologies may require a bit of effort for both parts, as users need to install and manage drivers and software, and developers need to integrate difficult technologies.

The motivation for this project is to provide easier access to this authentication method for the developer part, taking advantage of an already developed Java Applet similar to the one on this page.

Example Usage

The website Portal do Cidadão employs an authentication approach similar to what we are trying to achieve:

  • a homepage presents the user with a link;
  • ...which points to a new page, which includes the applet that handles the CC operations;
  • After these operations are done, the user is redirected to the original page, already authenticated and authorized.

The module will handle the simplification of integrating the authenticator into the homepage, and the ensuing session establishment on the website.

How does it work

The system has two components:

  • an Apache module capable of intercepting, reading and modifying received requests, as well as generate the adequate responses;
  • and a stub page developed on the target platform (in this case, PHP).

The first component detects incoming authentication requests and extracts the configuration parameters desired for the operation. Following that extraction, the module then generates the corresponding applet authentication page, ready to interact with the Citizen Card. Another situation that the module handles comes after the page has interacted with the CC, by intercepting a request generated by the applet, which contains signed data extracted from the CC. This XML data is then parsed into a new format, in order to be processed by the other component.

And this second component takes the parsed data and copies it over to session storage, after establishing it. The name of the fields is kept nearly the same as it was in the XML document, so identifying it is almost the same as it was in the original. After these operations are done, the user is redirected to the final page, already with the session initiated and filled. Note that the system doesn't destroy any session that was already initialized, although it may overwrite values that had the same name as the extracted XML data.

Sequence Diagrams

Gantt Chart

This charts shows the several tasks planned for this project, and their intended start and finish dates.

The up-to-date Gantt Project file for this plan can be found here.


  • the Applet page is not customizable;
  • there is no cryptographical validation of the server received XML data;
  • the access control to the stub page is done passing a random value, generated at server start-up;
  • it requires that the target platform can generate a stub page with the necessary functionality (session initiation and data manipulation).


  • ability to specify a template page to be returned with the configured applet, instead of hard-coding it;
  • validating the data returned via POST request by the applet, using cryptographic functions;
  • use the Apache Notes mechanism to transmit information to the stub page, eliminating the external weakness;
  • create additional stub pages for other languages.


Last modified 8 years ago Last modified on Sep 19, 2012, 9:44:13 PM

Attachments (5)

Download all attachments as: .zip