xdocs/index.xml - turbine-fulcrum-crypto - Git at Google

 <?xml version="1.0"?>
 <!--
     Licensed to the Apache Software Foundation (ASF) under one or
     more contributor license agreements. See the NOTICE file
     distributed with this work for additional information regarding
     copyright ownership. The ASF licenses this file to you under the
     Apache License, Version 2.0 (the "License"); you may not use
     this file except in compliance with the License. You may obtain
     a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0 Unless required by
     applicable law or agreed to in writing, software distributed
     under the License is distributed on an "AS IS" BASIS, WITHOUT
     WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     See the License for the specific language governing permissions
     and limitations under the License.
 -->
 <document>

     <properties>
         <title>Crypto Component</title>
         <author email="epugh@upstate.com">Eric PUgh</author>
     </properties>

     <body>
         <section name="Overview">
             <p>
                 The Crypto Service allows an application to request various encryption
                 algorithms.
             </p>

             <p>
                 It is written for use in Turbine but it can be used in any container
                 compatible with Avalon's ECM container.
             </p>
         </section>

         <section name="Configuration">
             <subsection name="Role Configuration">
                 <source><![CDATA[
     <role
         name="org.apache.fulcrum.crypto.CryptoService"
         shorthand="crypto"
         default-class="org.apache.fulcrum.crypto.DefaultCryptoService"/>
                 ]]></source>
             </subsection>

             <subsection name="Component Configuration">
               <table>
                 <tr>
                   <th>Item</th>
                   <th>Datatype</th>
                   <th>Cardinality</th>
                   <th>Description</th>
                 </tr>
                 <tr>
                   <td>algorithm</td>
                   <td>Complex</td>
                   <td>[0|1]</td>
                   <td>
                     This element controls the various encryption providers. All sub-elements
                     of this element define the name of the provider as the element name and
                     the class that implements the provider as its value. See the configuration
                     example. The algorithm <code>default</code> can be used to override the
                     default which is JavaCrypt.
                   </td>
                 </tr>
               </table>
             </subsection>

             <subsection name="Component Configuration Example">
               <source><![CDATA[
     <crypto>
       <algorithm>
         <unix>org.apache.fulcrum.crypto.provider.UnixCrypt</unix>
         <clear>org.apache.fulcrum.crypto.provider.ClearCrypt</clear>
         <java>org.apache.fulcrum.crypto.provider.JavaCrypt</java>
         <oldjava>org.apache.fulcrum.crypto.provider.OldJavaCrypt</oldjava>
       </algorithm>
     </crypto>
               ]]></source>
             </subsection>
         </section>

         <section name="Usage">
             <p>
                 If you want to encrypt a clear text with a MessageDigest Cipher, you
                 can do it like this:
             </p>

             <source><![CDATA[
 import org.apache.fulcrum.crypto.CryptoAlgorithm;
 import org.apache.fulcrum.crypto.CryptoService;

 public class CryptoExample
 {
     public String doMD5Encryption(String input)
     {
         CryptoService cs  = (CryptoService) avalonComponentService.lookup(CryptoService.ROLE);
         CryptoAlgorithm ca = CryptoService.getCryptoAlgorithm("default");

         ca.setCipher("MD5");

         return ca.encrypt(input);
     }
 }
 ]]></source>

             <p>
                 To see an example, look at the test case
                 <a href="xref-test/org/apache/fulcrum/crypto/CryptoServiceTest.html">CryptoServiceTest</a>.
             </p>
         </section>

         <section name="Default Provider">
             <p>
                 In the source code and the example above, there is talk
                 about a "default" provider which is used if no encryption algorithm is
                 specifically requested. The reason for this comes from the first user
                 of the crypto service, the
                 <a href="http://turbine.apache.org/turbine/turbine-2.3.3/services/security-service.html">Turbine Security Service</a>.
                 It gives you the
                 ability to select an encryption algorithm like MD5 or SHA1 which is in
                 turn used with the normal java crypto providers. As we just wanted to
                 "add" new algorithms and still be able to use the old java.security
                 names like MD5 and SHA1, we decided to add a "catchall" algorithm to
                 the crypto service.
             </p>
             <p>
                 If you don't set the default provider explicitly, the
                 org.apache.fulcrum.crypto.provider.JavaCrypt class is
                 used. If you don't set the Cipher of this class explicitly, then SHA
                 is used.
             </p>
         </section>

         <section name="Included Providers">
             <p>The following algorithm providers are included in the
                 Cryptoservice:</p>

             <p>
                 <ol>
                     <li>
                         <b>ClearCrypt</b>
                         (org.apache.fulcrum.crypto.provider.ClearCrypt).
                         This is the simplest algorithm which does nothing. It is still
                         useful because you can use the Crypto Service all the time even
                         if you don't want to actually encrypt something. Just request
                         the "clear" algorithm.
                     </li>
                     <li>
                         <b>UnixCrypt</b>
                         (org.apache.fulcrum.crypto.provider.UnixCrypt).
                         This is an implementation of the Unix crypt(3) algorithm. Its
                         main use is when you need to access legacy information or
                         databases which already contain crypted passwords.
                     </li>
                     <li>
                         <b>JavaCrypt</b>
                         (org.apache.fulcrum.crypto.provider.JavaCrypt).
                         This is the default crypto provider. It implements the normal
                         Java MessageDigest ciphers You don't need to have this, it is
                         the default if no algorithms are given. The default
                         provider gives you all the Java MessageDigest Ciphers including
                         MD5, and SHA1.
                     </li>
                     <li>
                         <b>OldJavaCrypt</b>
                         (org.apache.fulcrum.crypto.provider.OldJavaCrypt).
                         Accessing the MessageDigest functions from java.security was
                         buggy in Turbine 2.1, because the Security Service didn't pad
                         the base64 values correctly but simply cut them
                         off after 20 bytes. If you're stuck with an old database full of
                         passwords and can't upgrade, please use this provider to keep
                         going. DO NOT USE THIS PROVIDER FOR NEW APPLICATIONS!.
                     </li>
                 </ol>
             </p>
         </section>
     </body>
 </document>
	<?xml version="1.0"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or
	more contributor license agreements. See the NOTICE file
	distributed with this work for additional information regarding
	copyright ownership. The ASF licenses this file to you under the
	Apache License, Version 2.0 (the "License"); you may not use
	this file except in compliance with the License. You may obtain
	a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0 Unless required by
	applicable law or agreed to in writing, software distributed
	under the License is distributed on an "AS IS" BASIS, WITHOUT
	WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions
	and limitations under the License.
	-->
	<document>

	<properties>
	<title>Crypto Component</title>
	<author email="epugh@upstate.com">Eric PUgh</author>
	</properties>

	<body>
	<section name="Overview">
	<p>
	The Crypto Service allows an application to request various encryption
	algorithms.
	</p>

	<p>
	It is written for use in Turbine but it can be used in any container
	compatible with Avalon's ECM container.
	</p>
	</section>

	<section name="Configuration">
	<subsection name="Role Configuration">
	<source><![CDATA[
	<role
	name="org.apache.fulcrum.crypto.CryptoService"
	shorthand="crypto"
	default-class="org.apache.fulcrum.crypto.DefaultCryptoService"/>
	]]></source>
	</subsection>

	<subsection name="Component Configuration">
	<table>
	<tr>
	<th>Item</th>
	<th>Datatype</th>
	<th>Cardinality</th>
	<th>Description</th>
	</tr>
	<tr>
	<td>algorithm</td>
	<td>Complex</td>
	<td>[0\|1]</td>
	<td>
	This element controls the various encryption providers. All sub-elements
	of this element define the name of the provider as the element name and
	the class that implements the provider as its value. See the configuration
	example. The algorithm <code>default</code> can be used to override the
	default which is JavaCrypt.
	</td>
	</tr>
	</table>
	</subsection>

	<subsection name="Component Configuration Example">
	<source><![CDATA[
	<crypto>
	<algorithm>
	<unix>org.apache.fulcrum.crypto.provider.UnixCrypt</unix>
	<clear>org.apache.fulcrum.crypto.provider.ClearCrypt</clear>
	<java>org.apache.fulcrum.crypto.provider.JavaCrypt</java>
	<oldjava>org.apache.fulcrum.crypto.provider.OldJavaCrypt</oldjava>
	</algorithm>
	</crypto>
	]]></source>
	</subsection>
	</section>

	<section name="Usage">
	<p>
	If you want to encrypt a clear text with a MessageDigest Cipher, you
	can do it like this:
	</p>

	<source><![CDATA[
	import org.apache.fulcrum.crypto.CryptoAlgorithm;
	import org.apache.fulcrum.crypto.CryptoService;

	public class CryptoExample
	{
	public String doMD5Encryption(String input)
	{
	CryptoService cs = (CryptoService) avalonComponentService.lookup(CryptoService.ROLE);
	CryptoAlgorithm ca = CryptoService.getCryptoAlgorithm("default");

	ca.setCipher("MD5");

	return ca.encrypt(input);
	}
	}
	]]></source>

	<p>
	To see an example, look at the test case
	<a href="xref-test/org/apache/fulcrum/crypto/CryptoServiceTest.html">CryptoServiceTest</a>.
	</p>
	</section>

	<section name="Default Provider">
	<p>
	In the source code and the example above, there is talk
	about a "default" provider which is used if no encryption algorithm is
	specifically requested. The reason for this comes from the first user
	of the crypto service, the
	<a href="http://turbine.apache.org/turbine/turbine-2.3.3/services/security-service.html">Turbine Security Service</a>.
	It gives you the
	ability to select an encryption algorithm like MD5 or SHA1 which is in
	turn used with the normal java crypto providers. As we just wanted to
	"add" new algorithms and still be able to use the old java.security
	names like MD5 and SHA1, we decided to add a "catchall" algorithm to
	the crypto service.
	</p>
	<p>
	If you don't set the default provider explicitly, the
	org.apache.fulcrum.crypto.provider.JavaCrypt class is
	used. If you don't set the Cipher of this class explicitly, then SHA
	is used.
	</p>
	</section>

	<section name="Included Providers">
	<p>The following algorithm providers are included in the
	Cryptoservice:</p>

	<p>
	<ol>
	<li>
	<b>ClearCrypt</b>
	(org.apache.fulcrum.crypto.provider.ClearCrypt).
	This is the simplest algorithm which does nothing. It is still
	useful because you can use the Crypto Service all the time even
	if you don't want to actually encrypt something. Just request
	the "clear" algorithm.
	</li>
	<li>
	<b>UnixCrypt</b>
	(org.apache.fulcrum.crypto.provider.UnixCrypt).
	This is an implementation of the Unix crypt(3) algorithm. Its
	main use is when you need to access legacy information or
	databases which already contain crypted passwords.
	</li>
	<li>
	<b>JavaCrypt</b>
	(org.apache.fulcrum.crypto.provider.JavaCrypt).
	This is the default crypto provider. It implements the normal
	Java MessageDigest ciphers You don't need to have this, it is
	the default if no algorithms are given. The default
	provider gives you all the Java MessageDigest Ciphers including
	MD5, and SHA1.
	</li>
	<li>
	<b>OldJavaCrypt</b>
	(org.apache.fulcrum.crypto.provider.OldJavaCrypt).
	Accessing the MessageDigest functions from java.security was
	buggy in Turbine 2.1, because the Security Service didn't pad
	the base64 values correctly but simply cut them
	off after 20 bytes. If you're stuck with an old database full of
	passwords and can't upgrade, please use this provider to keep
	going. DO NOT USE THIS PROVIDER FOR NEW APPLICATIONS!.
	</li>
	</ol>
	</p>
	</section>
	</body>
	</document>