<?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>