App/CamelPKI version 0.02 ======================== To install this module type the usuall commands : perl Build.PL ./Build ./Build test ./Build install (which is not recommended as it will install the pki in perl libs) HOWTO CamelPKI Quick and Fast 1. Installation of the required softwares : Some applications must be installed in order CamelPKI to work : I give between parenthesis the name of the package in Ubuntu (add all default repository to sources.list). Under gentoo, fonctionnalities are controled by use flags that are generally well explained. - apache (apache2) : php5 (libapache2-mod-php5), perl(libapache2-mod-perl2) - php (php5-cli) : mod_json(php5-json), curl(php5-curl) - libssl0.9.8 - libssl-dev - libnet-ssleay-perl - build-essential So, to resume, under Ubuntu, for minimum requirements (tests won't all be runned) : In this case, the php front-end won't be usable with this apache instance(which is, by the way, not a good idea). #apt-get install apache2 apache2-threaded-dev libapache2-mod-perl2 build-essential libnet-ssleay-perl libssl-dev If you want to run the entire test suite, you need some other functionnalities. Install the with : #apt-get install libapache2-mod-php5 php5-common php5-cli php5-curl 2. Installation of the Perl Modules : You have to install some perl modules from CPAN in order to make work the application. cpan > install Module::Build File::Slurp MIME::Base64 Error DateTime Sys::Hostname IO::Socket::INET Config::General Config::Tiny XML::Simple Catalyst Catalyst::Plugin::ConfigLoader Catalyst::Plugin::Static::Simple Catalyst::Action::RenderView Catalyst::Engine::Apache JSON Catalyst::View::JSON SQL::Translator Crypt::X509 IPC::Run Test::Group Test::More Test::Builder File::Which File::Slurp File::Find Cwd Errno LWP::Simple LWP::UserAgent Convert::ASN1 IO::Socket::SSL Catalyst::View::TT HTTP::Request::Form Data::Dump DBD::SQLite DBIx::Class Crypt::OpenSSL::CA App::Info::HTTPD::Apache And if you want to run the full test suite and for devs environments: cpan> install Module::ScanDeps Test::NoBreakpoints Test::Pod::Coverage Catalyst::Helper For the moment, App::Crypt::OpenSSL::CA won't install because of failing tests. These tests fails because they aren't coded. You can install it by hand or by forcing it, making sure that only tests 12 and 13 of lib/Crypt/OpenSSL/CA are failing. 3. Extract the App-CamelPKI archive and create your own app_camelpki.yml (a sample can be found 'app_camelpki.yml.sample'). 3. Key Ceremony - Preparing the application A good idea here is to make whole files only readable by the user who executes apache.go into CamelPKI root directory and type : #chmod -R u+rw,g-rwx,o-rwx * It is also important to fix the right for the directories containing the different keys (as defined in app_camelpki.yml). Key ceremony is an important task to do. You have to generate your own Certificates and Private Keys for the CA. A script has been coded to do this easily : $ perl Build.PL $./Build $./script/camel_pki_keyceremony.pl var/ # Where the CA keys should be put. From this point, the CA Certificate's and key's can be found in the var/ directory. And now the tests : $./Build test 4. Launch the server Be sure, before this phase to complete your own config file ('app_camelpki.yml') If you have apache and mod_perl installed, you could launch the server with apache $./script/start_stop_camel_pki.pl start (stop in order to stop it) or you can use Catalyst itself : $./script/camel_pki_server.pl 5.Generate Client's certificate in order to generate and issue new client's certificates (we suppose key and certificates are contained in 'var/') For this operation we will use openssl : $ cat var/admin.key var/admin.pem > admin.glob $ openssl pkcs12 -in admin.glob -export -nodes -out cert.p12 From this point, the file cert.p12 is a certificate in pkcs12 format. It can be handled by your browser to authenticate on the PKI. 6.Enjoy the ride Simples pages are delivered. You can see them and generate certificates for SSL and VPN. With a form : https://ip:port/ca/template/ssl/certifyForm or https://ip:port/ca/template/vpn/certifyForm You can use the same kind of url with JSON parameters. https://ip:port/ca/template/ssl/certifyJSON for example.(see in t/ and t/php/ for sample). By default, the port used with apache is defined in app_camelpki.yml and is 3000 if you are usng Catalyst. TESTED PLATFORMS This package has been test under Ubuntu Hardy Heron,Intrepid Ibex and Gentoo (2006.1 and 2007.0 as these lines are written. SAMPLES Please, consult t/php/README for php code samples. COPYRIGHT AND LICENCE Copyright 2008 This program is free software; you can redistribute it following the same terms as Perl itself.