xdocs/services/crypto-service.xml - turbine-core - Git at Google

 <?xml version="1.0"?>
 <!--
 /*
  * Copyright 2001-2004 The Apache Software Foundation.
  *
  * Licensed 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 Service</title>
   </properties>

 <body>

 <section name="Crypto Service">

 <p>
 The Crypto Service allows an application to request various encryption
 algorithms provided by the normal Java crypto providers and 3rd party
 providers such as <a href="http://www.cryptix.org/">Cryptix</a>.
 </p>

 </section>

 <section name="Configuration">

 <source><![CDATA[
 # -------------------------------------------------------------------
 #
 #  S E R V I C E S
 #
 # -------------------------------------------------------------------
 # Classes for Turbine Services should be defined here.
 # Format: services.[name].classname=[implementing class]
 #
 # To specify properties of a service use the following syntax:
 # service.[name].[property]=[value]

 services.CryptoService.classname=org.apache.turbine.services.crypto.TurbineCryptoService
 .
 .
 .
 # -------------------------------------------------------------------
 #
 #  C R Y P T O   S E R V I C E
 #
 # -------------------------------------------------------------------

 #
 # Standard Unix crypt(3) password encryption.
 #
 services.CryptoService.algorithm.unix  = org.apache.turbine.services.crypto.provider.UnixCrypt
 #
 # This providers allows access to the Java Message Digest encryption algorithms
 #
 services.CryptoService.algorithm.java  = org.apache.turbine.services.crypto.provider.JavaCrypt
 #
 # This is a simple, cleartext "encryption" provider.
 #
 services.CryptoService.algorithm.cleartext  = org.apache.turbine.services.crypto.provider.ClearCrypt
 #
 # Use this provider if you upgrade from Turbine 2.1 to current. It provides bug-to-bug
 # compatibility for passwords created with the old Security Service. See the javadocs for
 # OldJavaCrypt
 #
 services.CryptoService.algorithm.oldjava  = org.apache.turbine.services.crypto.provider.OldJavaCrypt
 #
 # This is the default crypto provider. It implements the normal Java MessageDigest ciphers
 # You need not to have this, it is the default if no algorithms are given. The default
 # provider gives you all the Java MessageDigest Ciphers
 #
 services.CryptoService.algorithm.default  = org.apache.turbine.services.crypto.provider.JavaCrypt


 ]]></source>

 </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.turbine.services.crypto.CryptoAlgorithm;
 import org.apache.turbine.services.crypto.TurbineCrypto;

 public class CryptoExample
 {
     public String doMD5Encryption(String input)
     {
         CryptoAlgorithm ca = TurbineCrypto.getCryptoAlgorithm("default");

         ca.setCipher("MD5");

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

 </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="security-service.html">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.turbine.services.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.turbine.services.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 "cleartext" algorithm.
 </li>
 <li>
 <b>UnixCrypt</b> (org.apache.turbine.services.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. UnixCrypt needs the cryptix32.jar from <a
 href="http://www.cryptix.org/">Cryptix</a>.
 </li>
 <li>
 <b>JavaCrypt</b> (org.apache.turbine.services.crypto.provider.JavaCrypt). This is a
 wrapper around the java.security Message Digest functions which give
 you MD5, SHA1 and more algorithms.
 </li>
 <li>
 <b>OldJavaCrypt</b> (org.apache.turbine.services.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"?>
	<!--
	/*
	* Copyright 2001-2004 The Apache Software Foundation.
	*
	* Licensed 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 Service</title>
	</properties>

	<body>

	<section name="Crypto Service">

	<p>
	The Crypto Service allows an application to request various encryption
	algorithms provided by the normal Java crypto providers and 3rd party
	providers such as <a href="http://www.cryptix.org/">Cryptix</a>.
	</p>

	</section>

	<section name="Configuration">

	<source><![CDATA[
	# -------------------------------------------------------------------
	#
	# S E R V I C E S
	#
	# -------------------------------------------------------------------
	# Classes for Turbine Services should be defined here.
	# Format: services.[name].classname=[implementing class]
	#
	# To specify properties of a service use the following syntax:
	# service.[name].[property]=[value]

	services.CryptoService.classname=org.apache.turbine.services.crypto.TurbineCryptoService
	.
	.
	.
	# -------------------------------------------------------------------
	#
	# C R Y P T O S E R V I C E
	#
	# -------------------------------------------------------------------

	#
	# Standard Unix crypt(3) password encryption.
	#
	services.CryptoService.algorithm.unix = org.apache.turbine.services.crypto.provider.UnixCrypt
	#
	# This providers allows access to the Java Message Digest encryption algorithms
	#
	services.CryptoService.algorithm.java = org.apache.turbine.services.crypto.provider.JavaCrypt
	#
	# This is a simple, cleartext "encryption" provider.
	#
	services.CryptoService.algorithm.cleartext = org.apache.turbine.services.crypto.provider.ClearCrypt
	#
	# Use this provider if you upgrade from Turbine 2.1 to current. It provides bug-to-bug
	# compatibility for passwords created with the old Security Service. See the javadocs for
	# OldJavaCrypt
	#
	services.CryptoService.algorithm.oldjava = org.apache.turbine.services.crypto.provider.OldJavaCrypt
	#
	# This is the default crypto provider. It implements the normal Java MessageDigest ciphers
	# You need not to have this, it is the default if no algorithms are given. The default
	# provider gives you all the Java MessageDigest Ciphers
	#
	services.CryptoService.algorithm.default = org.apache.turbine.services.crypto.provider.JavaCrypt


	]]></source>

	</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.turbine.services.crypto.CryptoAlgorithm;
	import org.apache.turbine.services.crypto.TurbineCrypto;

	public class CryptoExample
	{
	public String doMD5Encryption(String input)
	{
	CryptoAlgorithm ca = TurbineCrypto.getCryptoAlgorithm("default");

	ca.setCipher("MD5");

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

	</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="security-service.html">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.turbine.services.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.turbine.services.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 "cleartext" algorithm.
	</li>
	<li>
	<b>UnixCrypt</b> (org.apache.turbine.services.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. UnixCrypt needs the cryptix32.jar from <a
	href="http://www.cryptix.org/">Cryptix</a>.
	</li>
	<li>
	<b>JavaCrypt</b> (org.apache.turbine.services.crypto.provider.JavaCrypt). This is a
	wrapper around the java.security Message Digest functions which give
	you MD5, SHA1 and more algorithms.
	</li>
	<li>
	<b>OldJavaCrypt</b> (org.apache.turbine.services.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>