<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent">
%BOOK_ENTITIES;
]>
<section id="sect-Reference_Guide-Password-encryption">
	<title>Password Encryption</title>
	<para>
     The automatic login - a feature of GateIn portal that automatically authenticates returning users without prompting for username and password, is implemented with the token mechanism.
     When an anonymous user logs in with the 'Remember My Login' option, a token entity holding his/her credential is generated and stored on server-side and the token ID is sent back to the client-side
     under the "rememberme" cookie.
	</para>
	<para>This feature wraps encrypted passwords in persistent tokens that are decoded to transparently authenticate the user when he attempts to access any page of the portal. From the security perspective, there are two important things to consider: 
	</para>
     <itemizedlist>
       <listitem>
         <para>Default token encryption: By default, no extra configuration is required to have secure tokens. Default encryption factors are applied to make sure the system is out of the box. Check for the <ulink url="../../../admin-guide/html/ADM.Security.Key_Rememberme_token.html">Update the password encryption key of the RememberMe token</ulink> section of Administrator Guide for more details.</para>
		</listitem>
       <listitem>
         <para>Customize encryption parameters: You can set several parameters to match with your own security policy.</para>
       </listitem>
     </itemizedlist>

  <section id="sect-Reference_Guide-Password-encryption-Customizing-Encryption-Factors">
    <title>Customize security parameters</title>
    <para>
      You can generate your own secret keys using the JDK's keytool command, then update the configuration to use those secret keys for the password encryption. 
    </para>
        <para>The symetric encryption is built over JCA. JCA is a Java Cryptography Architecture library whose default algorithm is <ulink url="http://en.wikipedia.org/wiki/Advanced_Encryption_Standard">AES</ulink>.
        </para>
		<para>
          <citetitle>
			<emphasis role="bold">Do a JCA-based encryption</emphasis>
		  </citetitle>
		</para>
		<para>
		There are 2 main sub-tasks in the process of JCA-based encryption.
		</para>
		<para><emphasis role="bold">Configuration</emphasis></para>
				<itemizedlist>
					<listitem>
					<para>The default configuration entry of JCA-based encryption is declared in the <emphasis>configuration.properties</emphasis> file.</para>
<programlisting language="java">
gatein.codec.builderclass=org.exoplatform.web.security.codec.JCASymmetricCodecBuilder
gatein.codec.config=${gatein.conf.dir}/codec/jca-symmetric-codec.properties
</programlisting>
					</listitem>
					<listitem>
					<para>The detailed parameters for encryptions whose builder is <emphasis role="italic">org.exoplatform.web.security.codec.JCASymmetricCodecBuilder</emphasis> are referred in the <emphasis>jca-symmetric-codec.properties</emphasis> file.</para>
<programlisting language="java">
# Detailed information on JCA standard names could be found at
#
# http://docs.oracle.com/javase/6/docs/technotes/guides/security/StandardNames.html#KeyStore
#
# The file key.txt is generated via keytool util in JDK
#
# keytool -genseckey -alias "gtnKey" -keypass "gtnKeyPass" -keyalg "AES" -keysize 128 -keystore "key.txt" -storepass "gtnStorePass" -storetype "JCEKS"
#
#
gatein.codec.jca.symmetric.alias=gtnKey
gatein.codec.jca.symmetric.keypass=gtnKeyPass
gatein.codec.jca.symmetric.keyalg=AES
gatein.codec.jca.symmetric.keystore=key.txt
gatein.codec.jca.symmetric.storepass=gtnStorePass
gatein.codec.jca.symmetric.storetype=JCEKS
</programlisting>
					</listitem>
				</itemizedlist>
		<para><emphasis role="bold">Customization</emphasis></para>
				  <para>A crucial point of the encryption is that secret factors (algorithm, key storage, key size, and more) are created/maintained on the customer side.</para>
				  <para>Below are steps to customize those secret factors in products using <emphasis role="bold">JCASymmmetricCodecBuilder</emphasis>.</para>
		<procedure>
		<step>
          <para>
            Generate the secret key via keytool.
          </para>
<programlisting><![CDATA[
$JAVA_HOME/bin/keytool -genseckey -alias "customAlias" -keypass "customKeyPass" -keyalg "customAlgo" -keystore "customStore" -storepass "customStorePass" -storetype "customStoreType"
]]>
</programlisting>
    
<note>
<para>
The above keytool command generates the secret key stored in a file named <emphasis>customStore</emphasis>. Remember to copy the <emphasis>customStore</emphasis> file to the <emphasis>gatein/conf/codec</emphasis> directory.
</para>
</note>
        </step>
		<step>
          <para>
            Update the <emphasis>jca-symmetric-codec.properties</emphasis> file with the parameters used in Step 1.
		  </para>
<programlisting language="java"><![CDATA[
gatein.codec.jca.symmetric.alias=customAlias
gatein.codec.jca.symmetric.keypass=customKeyPass
gatein.codec.jca.symmetric.keyalg=customAlgo
gatein.codec.jca.symmetric.keystore=customStore
gatein.codec.jca.symmetric.storepass=customStorePass
gatein.codec.jca.symmetric.storetype=customStoreType
]]>
</programlisting>
</step>
</procedure>
</section>
</section>
