Extended documentation.

git-svn-id: https://joinup.ec.europa.eu/svn/mocca/trunk@739 8a26b1a7-26f0-462f-b9ef-d0e30c41f5a4

3 files changed, 148 insertions, 0 deletions

diff --git a/BKUOnline/src/site/apt/configuration.apt b/BKUOnline/src/site/apt/configuration.apt
new file mode 100644
index 00000000..38b05e12
--- /dev/null
+++ b/BKUOnline/src/site/apt/configuration.apt
@@ -0,0 +1,56 @@
+	---
+	Configuration
+	---
+	EGIZ
+	---
+	2010
+	---
+	
+MOCCA Online Configuration
+
+	MOCCA Online comes with a reasonable default configuration. Therefore, providing your own configuration is only required when you need configuration options different from the default parameters.
+	
+	Since MOCCA version 1.3 a configuration resource may be specified as servlet context init parameter. This allows to keep your configuration resource outside of the deployed servlet context and to redeploy the web application without overwriting your configuration resource.
+	
+	To specify your own configuration {{{http://static.springsource.org/spring/docs/2.5.5/reference/resources.html}resource}} simply set the corresponding servlet context init parameter <<<configurationResource>>>. Please refer to the documentation of your servlet container on how to set servlet context initialization parameters. Usually this is done via the <<<web.xml>>> file in your web application.
+	
+	<<<WEB-INF/web.xml>>>:
+	
++------------------+
+...
+<web-app>
+
+  ...
+  <context-param>
+    <param-name>configurationResource</param-name>
+    <param-value>file://mocca/configuration.xml</param-value>
+  </context-param>
+  ...
+
+</web-app>
++------------------+
+
+	The value of the <<<configurationResource>>> parameter must be a valid {{{http://static.springsource.org/spring/docs/2.5.5/reference/resources.html}Spring resource}} name. Placeholders such as <<<$\{user.home\}>>> are also supported (via {{{http://static.springsource.org/spring/docs/2.5.5/api/org/springframework/beans/factory/config/PropertyPlaceholderConfigurer.html}Spring's Property Placeholder Configurer}}).
+	
+* Apache Tomcat	
+	
+	In addition to the specifying init parameters in the <<<web.xml>>> Apache Tomcat also allows to provide a file named <<<$CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml>>> (e.g. <<<.../conf/Catalina/localhost/mocca.xml>>>) to specify context parameters. See also {{http://tomcat.apache.org/tomcat-6.0-doc/config/context.html}}.
+	
+	The <<<configurationResource>>> parameter may be specified like the following:
+	
++------------------+
+
+<?xml version="1.0" encoding="UTF-8"?>
+<Context>
+
+  <Parameter name="configurationResource" value="file:${user.home}/mocca/configuration.xml" override="false"/>
+
+</Context>
+
++------------------+
+
+	This way the init parameter is not overwritten when the web application is redeployed.
+	
+* Configuration Options
+
+	For the available configuration options please see {{{../bkucommon/configuration.html}MOCCA Configuration}}.
\ No newline at end of file
diff --git a/BKUOnline/src/site/apt/deployment.apt b/BKUOnline/src/site/apt/deployment.apt
new file mode 100644
index 00000000..844b8d58
--- /dev/null
+++ b/BKUOnline/src/site/apt/deployment.apt
@@ -0,0 +1,77 @@
+	---
+	Deployment
+	---
+	EGIZ
+	---
+	2010
+	---
+	
+MOCCA Online Deployment
+
+	We have tried to keep the deployment procedure of MOCCA Online as simple as possible. In the standard case, all you need to do is download the appropriate war file and deploy it usign the standard deployment mechanism of your favorite servlet container.
+	
+    [Note: <<<war>>> File Deployment] 
+    
+    MOCCA assumes that the war file is unpacked upon deployment by the servlet container (which is the standard case e.g. in Apache Tomcat). 
+    
+    MOCCA requires proper directories for the certificate and trust stores. It is therefore possible to deploy and run MOCCA from the packed war file, but you need to provide your own configuration resource as described in {{{./configuration.html}Configuration}} in such a case. This configuration resource must provide URLs for the certificate and trust stores that resolve to proper directories (see {{{/bkucommon/configuration.html}MOCCA Configuration}}).
+    
+    []
+    
+    [Note: {Java Cryptographic Service Providers}]
+    
+    MOCCA requires some Java {{{http://java.sun.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html#ProviderArch}Cryptographic Service Providers}} to be registered.
+    
+    To allow for a simple deployment in the standard case MOCCA tries to register any required and not yet registered Cryptographic Service Providers upon startup. Since such security providers can only be registered statically with the class <<<{{{http://java.sun.com/javase/6/docs/api/java/security/Security.html}java.security.Security}}>>> which is load by a class loader shared by all servlet contexts (see {{{http://tomcat.apache.org/tomcat-6.0-doc/class-loader-howto.html}Apache Tomcat Class Loader How-To}}) the registered security providers are also visibile to other servlet contexts in the same container. This may affect other web applications in the same servlet container!
+    
+    When the security providers registered with the class <<<java.security.Security>>> have been load by the context class loader of one servlet context they are <visible but not usable> by servlets in another servlet context. This may cause other web applications in the same servlet container to fail!
+    
+    Therefore, <<when deploying MOCCA together with other web applications>> in the same servlet container (e.g. Apache Tomcat) <<make sure any Cryptographic Service Providers registered>> with the class <<<java.security.Security>>> <<are load by a shared class loader>>.
+    
+    There are (at least) two possibilities to accomplish this:
+    
+    	[[A]] 
+    	
+    	Make sure to remove the following <<<jar>>> files from the <<<WEB-INF/lib>>> directory of your deployed MOCCA web application (archive)
+    		
+    		* <<<iaik_jce_full_signed-*.jar>>>
+    		
+    		* <<<iaik_ecc_signed-*.jar>>>
+    		
+    		* <<<iaik_xsect-*.jar>>>
+    		
+    	and place them into the appropriate directory accessible by the shared class loader (e.g. <<<$CATALINA_HOME/lib>>> for Apache Tomcat).
+    	
+    	[[A]] 
+    	
+    	Register the security providers statically  with your Java VM as explained in {{{http://java.sun.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html#ProviderInstalling}Provider Installing}}. The classes
+    	    	
+    		* <<<iaik.security.provider.IAIK>>>
+    		
+    		* <<<iaik.security.ecc.provider.ECCProvider>>>
+    		
+    	should be registered at first and second position. And the class
+    	
+    		* <<<iaik.xml.crypto.XSecProvider>>>
+    		
+    	must be registered before any other XMLDSig provider (e.g. <<<org.jcp.xml.dsig.internal.dom.XMLDSigRI>>>).
+    	
+    	You may then tell MOCCA to omit the provider registration via the <<<RegisterSecurityProviders>>> {{{/bkucommmon/configuration.html}configuration parameter}}. However, this is not required as MOCCA detects already registered providers.
+    
+	[]
+	
+* Deploying MOCCA Online in Apache Tomcat 6.0
+
+	If MOCCA Online is the only application going to be deployed in Tomcat all you need to do is:
+
+	[[]] Copy the MOCCA Online <<<war>>> file to the <<<./webapps>>> directory of your Tomcat installation.
+	
+	[[]] Optionally rename the <<<war>>> file to match the desired context name (e.g. <<<mocca.war>>> for a web application context of <<</mocca>>>).
+	
+	[[]] Startup Tomcat. 
+	
+	[]
+	
+	MOCCA Online should now be accessible by directing your browser to {{http://localhost:8080/mocca/}} (replace <<<mocca>>> with the name of your war file).
+	
+	If other web applications are deployed into the same Tomcat instance, your may also need to perform the steps in the Note on {{Java Cryptographic Service Providers}} above.
\ No newline at end of file
diff --git a/BKUOnline/src/site/apt/index.apt b/BKUOnline/src/site/apt/index.apt
new file mode 100644
index 00000000..3ea0fdcd
--- /dev/null
+++ b/BKUOnline/src/site/apt/index.apt
@@ -0,0 +1,15 @@
+	---
+	MOCCA Online
+	---
+	EGIZ
+	---
+	2010
+	---
+
+
+MOCCA Online
+
+	MOCCA Online (aka <BKUOnline>) provides a new approach for an implementation of a {{{http://www.buergerkarte.at/konzept/securitylayer/spezifikation/20040514/Index.en.html}citizen card environment}} that overcomes the need to install dedicated software on the user's PC. MOCCA Online is <to be installed as online service> (usually together with a citizen card enabled web application) by a service provider. It offers the same interfaces and protocol bindings for integration with applications via the user's browser as a citizen card environment installed on the user's PC. Access to the user's citizen card and user interaction is performed via a Java Applet. Therefore, a user only needs a properly installed (PC/SC supported) card reader and a recent version of the Java browser plug-in to be able to use a citizen card with MOCCA Online.
+	
+	Releases can be found in the {{{http://egovlabs.gv.at/frs/?group_id=13}download}} section. For installation of MOCCA Online see {{{./deployment.html}Deployment}} and {{{./configuration.html}Configuration}}.
+	
\ No newline at end of file